法的情報

DirectX 8
プログラマーズ リファレンス

本書に記載されている情報は、URL およびインターネット Web サイトの参照も含めて、予告なしに変更されることがあります。本書で例として取りあげる企業、組織、製品、人物、およびイベントはすべて架空のものです。実在の企業、組織、製品、人物、またはイベントとの関連性を示唆するものではありません。本書の使用にあたっては、お客様の責任において、適用されるすべての著作権法に従ってください。著作権法による権利の制限内にとどまらず、また、使用目的にかかわらず、Microsoft Corporation からの書面による許可なく、本書の一部または全部を無断で複製したり、検索システムに格納または導入したり、あるいはいかなる形式や手段 (電子的、機械的、複写、録音、その他) でも配信することはできません。

Microsoft は、本書の内容に関連する特許、特許申請、商標、著作権、その他の知的所有権を有する場合があります。Microsoft からのライセンス契約文書で明示的に規定されていない限り、本書を入手しても Microsoft から上記特許、商標、著作権、その他の知的所有権のいずれのライセンスを取得したことにもなりません。

© 1995-2000 Microsoft Corporation.All rights reserved.

Microsoft、MS-DOS、Windows、Windows NT、ActiveX、Direct3D、DirectAnimation、DirectDraw、DirectInput、DirectMusic、DirectPlay、DirectShow、DirectSound、DirectX、Natural、および Win32 は、米国およびその他の各国における Microsoft Corporation の登録商標または商標です。

Roland GS Sound Set/Microsoft (R) 1996 Roland Corporation U.S.

Roland は Roland Corporation の登録商標です。

本書に記載されている実在の会社名および製品名は、各社の商標です。

注 : この API を実装する通信デバイスのメーカーは、1996 年の通信法第 255 条 (Section 255 of the Telecommunications Act) に準拠している必要があります。

著作権に関する注意

特別な注意 Roland GS Sound Set/Microsoft、つまり "サンプル セット" にはローランド サウンドキャンバス サウンド セットが組み込まれています。米国 Roland Corporation は、サンプル セットとそれに関連するすべての著作権を保有しています。さらに、サンプル セットの使用は、Microsoft のオペレーティング システム製品およびアプリケーション製品でのみ許可されています。

Microsoft の使用許諾契約書の条項で、サンプル セットに関して米国 Roland Corporation または Microsoft によって明白に許可されていない権利は、すべてローランドが保有します。

サンプル セットの再頒布は、Microsoft オペレーティング システム製品の統合コンポーネントとして、Microsoft の使用許諾契約書の条項に従って、ソフトウェア アプリケーションと一緒に行う場合にのみ認められます。サンプル セットをその他の用途に使用する場合は、米国 Roland Corporation からの別の書面による許可が必要となります。

米国 Roland Corporation の法的権限を持つ代表者による書面による事前承認なく、サンプル セットをハードウェア ROM または同様のデバイスで、使用、複写、または再頒布することはできません。また、サンプル セットを何らかの楽器と共に再頒布することはできません。"楽器" とは、ライセンスされた Microsoft オペレーティング システムを実行しているコンピュータに直接接続しなくても、音楽のサウンドを生成することができるデバイスのことです。いかなる環境においても、サンプル セットを修正することは許可されていません。

Built on 2000年11月18日


DirectX 8.0 の紹介

Microsoft® DirectX® は、ゲームおよびその他のハイパフォーマンスなマルチメディア アプリケーションを作成するための下位レベルのアプリケーション プログラミング インターフェイス (API) のセットである。Microsoft® DirectX® は、2 次元 (2D) と 3 次元 (3D) のグラフィックス、サウンド エフェクトとミュージック、入力デバイス、マルチプレーヤー ゲームなどのネットワーク アプリケーションをサポートする。

このドキュメントでは、DirectX 8.0 に関する概要を記述する。説明するトピックは、次のとおりである。

  • DirectX 8.0 の新機能
  • DirectX 8.0 ドキュメントの使い方
  • DirectX 8.0 のコンポーネント
  • DirectX ツール
  • Visual Basic を使用した DirectX のプログラミング
  • 参考資料


DirectX 8.0 の新機能

Microsoft® DirectX® 8.0 でサポートされている新機能のいくつかを以下に示す。

DirectDraw と Direct3D の完全な統合
Microsoft DirectDraw® と Microsoft Direct3D® は単一の DirectX Graphics コンポーネントに統合された。API は大きく変更され、より一層使いやすくなり、最新のグラフィックス ハードウェアがサポートされるようになった。
DirectMusic と DirectSound の統合の強化
Microsoft DirectMusic® と Microsoft DirectSound® の統合が、DirectX 7.0 よりも強化された。ウェーブ ファイルやリソースを DirectMusic ローダーでロードして、MIDI ノートと同期される DirectMusic パフォーマンスで演奏できるようになった。
DirectPlay のアップデート
Microsoft DirectPlay® コンポーネントは大きく拡張されて機能が増え、しかもさらに使いやすくなった。特に DirectPlay では、プレーヤー間の音声通信がサポートされるようになった。
DirectInput のアップデート
Microsoft DirectInput® に主要な機能が追加された。それは、アクション マッピングである。アクション マッピングを使用すると、特定のデバイス オブジェクトに依存せずに、入力アクションと入力デバイス間の接続を確立できる。そのため、入力ループが簡単になり、カスタム ゲーム ドライバ、カスタム デバイス プロファイラ、およびゲームのカスタム構成ユーザー インターフェイスの必要性が低下する。
デバッグ ビルドが利用可能
DirectX コントロール パネル アプリケーションを使用すると、DirectInput、Direct3D、および DirectMusic のデバッグ ビルドとリテール ビルドを切り替えることができる。この機能を有効にするには、SDK をインストールするときにデバッグ オプションを選択する。このオプションを選択すると、システムには DLL のデバッグ バージョンとリテール バージョンがインストールされる。リテール オプションを選択した場合は、DLL のリテール バージョンだけがインストールされる。


DirectX 8.0 ドキュメントの使い方

以下の表記は説明や簡単なコードのほか、メソッド、関数、およびその他の API 要素の構文で使用される。

表記 | 意味
Italic text (斜体文字列) | プレースホルダまたは変数を表す。ここには実際の値を入れる必要がある。たとえば、本文に SetCursorPos(X, Y) と書かれていた場合、実際のコードでは X および Y の部分には具体的な値を入れなければならない。
Bold text (太字文字列) | プログラミング インターフェイスや言語などでの関数、プロシージャ、構造体、マクロ、インターフェイス、メソッド、データ型、およびその他のキーワードを表す。
[] | 省略可能なパラメータを示す。
... | 直前の項目を繰り返し記述できることを示す。
FULL BOLD CAPITALS (すべて太字の大文字) | 多くの型 (タイプ) と構造体の名前に使用される。
FULL CAPITALS （すべて大文字） | 列挙値、フラグ、および定数に使用される。
monospace (モノスペース) | コード例と構文のスペースに使用される。
. . . | サンプル アプリケーションでの省略部分を示す。


DirectX 8.0 のコンポーネント

Microsoft® DirectX® 8.0 は以下のコンポーネントで構成される。

  • DirectX Graphics は、DirectX の前バージョンの Microsoft DirectDraw® コンポーネントと Microsoft Direct3D® コンポーネントが結合された単一の API であり、すべてのグラフィックス プログラミングに使用できる。コンポーネントには、多くのグラフィックス プログラミング作業を簡単にする Direct3DX ユーティリティ ライブラリが含まれる。
  • DirectX Audio は、前バージョンの DirectX の Microsoft DirectSound® コンポーネントと DirectMusic® コンポーネントが結合された単一の API であり、すべてのオーディオ プログラミングに使用できる。
  • Microsoft DirectInput® は、フォース フィードバック テクノロジのフル サポートなど、さまざまな入力デバイスをサポートしている。
  • Microsoft DirectPlay® は、マルチプレーヤー用ネットワーク ゲームをサポートする。
  • Microsoft DirectShow® Visual Basic® ドキュメントは C++ ドキュメントと密接に結びついて説明されている。DirectShow 編集サービス (DES) を含む DirectShow Visual Basic プログラミングの情報は C++ ドキュメントの付録に主に記載されている。分割された Visual Basic ドキュメントはない。


DirectX ツール

以下のツールは、Microsoft® DirectX® アプリケーションの開発とトラブルシューティングに利用できる。

  • DirectX Caps Viewer
  • DirectX コントロール パネル アプリケーション
  • DirectX Diagnostic Tool


DirectX Caps Viewer

説明

DirectX Caps Viewer ツールは、Microsoft® DirectX® のすべてのコンポーネントのデバイスと機能を列挙する。

パス

実行可能ファイル : (SDK ルート)\Bin\DXUtils\DXCapsViewer.exe

ユーザーズ ガイド

ツリー ビューでトピックを選択する。右側のペインに情報が表示される。


DirectX コントロール パネル アプリケーション

SDK と共にインストールされる Microsoft® DirectX® コントロール パネル ユーティリティを使用すると、DirectX コンポーネントのプロパティを調べたり変更することができる。このユーティリティには、各 DirectX コンポーネント用のタブが含まれる。このユーティリティを使うと、次のような作業が可能である。

  • DirectX コンポーネントのバージョン情報を取得する。
  • 開発プロセスでトラブルシューティングに役立つデバッグ出力レベルおよびデバッグ設定を変更する。
  • DirectX コンポーネントの特定のドライバおよびハードウェア サポート情報を表示する。
  • Microsoft Direct3D®、DirectMusic®、および DirectInput® のランタイムをデバッグ バージョンとリテール バージョンの間で切り替える。


DirectX Diagnostic Tool

説明

Microsoft® DirectX® Diagnostic Tool は、コンポーネントが正常に機能しているかどうかをテストするだけでなく、システムとシステムにインストールされている DirectX コンポーネントの情報を収集する。DirectX SDK と共にインストールされるこのツールの特別バージョンを使うことにより、開発者は DirectX 開発チームに問題を直接報告できる。

パス

実行可能ファイル : (Windows ルート)\System32\Dxdiag.exe

ユーザーズ ガイド

DirectX Diagnostic Tool ヘルプ ファイルを表示するには、[Help] ボタンをクリックする。


C または C++ による DirectX プログラミング

ここでは、C++ でのアプリケーション開発について説明する。


COM の使い方

ここでは、C++ でのアプリケーション開発について説明する。


COM オブジェクトとは

ここでは、C++ でのアプリケーション開発について説明する。


COM オブジェクトの作成

ここでは、C++ でのアプリケーション開発について説明する。


COM インターフェイスの使い方

ここでは、C++ でのアプリケーション開発について説明する。


追加のインターフェイスの要求

ここでは、C++ でのアプリケーション開発について説明する。


COM オブジェクトの寿命の管理

ここでは、C++ でのアプリケーション開発について説明する。


C による COM オブジェクトへのアクセス

ここでは、C++ でのアプリケーション開発について説明する。


マクロによる DirectX COM メソッドの呼び出し

ここでは、C++ でのアプリケーション開発について説明する。


DirectX COM ドキュメントの表記規則

ここでは、C++ でのアプリケーション開発について説明する。


IUnknown インターフェイス

ここでは、C++ でのアプリケーション開発について説明する。


IUnknown::AddRef

ここでは、C++ でのアプリケーション開発について説明する。


IUnknown::QueryInterface

ここでは、C++ でのアプリケーション開発について説明する。


IUnknown::Release

ここでは、C++ でのアプリケーション開発について説明する。


コールバック関数の使い方

ここでは、C++ でのアプリケーション開発について説明する。


コールバック関数の実装

ここでは、C++ でのアプリケーション開発について説明する。


バージョン チェック

ここでは、C++ でのアプリケーション開発について説明する。


オペレーティング システムのバージョンのチェック

ここでは、C++ でのアプリケーション開発について説明する。


DirectX のサンプルおよびその他の DirectX アプリケーションのコンパイル

ここでは、C++ でのアプリケーション開発について説明する。


コンパイルの準備

ここでは、C++ でのアプリケーション開発について説明する。


コンポーネントのバージョン定数

ここでは、C++ でのアプリケーション開発について説明する。


DirectX アプリケーションのデバッグ

ここでは、C++ でのアプリケーション開発について説明する。


デバッグ用とリテール用の DLL

ここでは、C++ でのアプリケーション開発について説明する。


DirectX 8.0 エラー処理ユーティリティ ライブラリ

ここでは、C++ でのアプリケーション開発について説明する。


DirectX 8.0 エラー処理関数

ここでは、C++ でのアプリケーション開発について説明する。


DXGetErrorString8

ここでは、C++ でのアプリケーション開発について説明する。


DXTrace

ここでは、C++ でのアプリケーション開発について説明する。


DirectX 8.0 エラー処理マクロ

ここでは、C++ でのアプリケーション開発について説明する。


DXTRACE_MSG

ここでは、C++ でのアプリケーション開発について説明する。


DXTRACE_ERR

ここでは、C++ でのアプリケーション開発について説明する。


DXTRACE_ERR_NOMSGBOX

ここでは、C++ でのアプリケーション開発について説明する。


Visual Basic を使用した DirectX のプログラミング

ここでは、Microsoft® DirectX® for Microsoft Visual Basic® を使用したアプリケーションの開発について説明する。

説明するトピックは、次のとおりである。

  • タイプ ライブラリの参照
  • DirectX オブジェクトの作成
  • GUID の使い方
  • メソッドへの配列の受け渡し
  • フラグの使い方
  • ビットマスクの使い方
  • DirectX の列挙
  • IUnknown データ型
  • エラー処理
  • DirectX クラスのリファレンス


タイプ ライブラリの参照

プロジェクトで Microsoft® DirectX® for Microsoft Visual Basic® を使用するためには、まずそのプロジェクトにタイプ ライブラリへのアクセス権があることを確認する必要がある。

プロジェクトにタイプ ライブラリへのアクセス権があることを確認するには、次の手順を実行する。

  1. Microsoft Visual Studio® で [プロジェクト] メニューの [参照設定] をクリックする。
  2. [DirectX 8 for Visual Basic Type Library] をクリックし、[OK] をクリックする。


DirectX オブジェクトの作成

Microsoft® DirectX® for Microsoft Visual Basic® アプリケーションはすべて、DirectX8 オブジェクトを備えている必要がある。DirectX8 オブジェクトは、各 DirectX コンポーネントに対して主要なオブジェクトを作成するときに使用するメソッドの親オブジェクトである。DirectX8 オブジェクトには、Microsoft Direct3D® の計算を実行するメソッドなど、その他にも多数のメソッドがある。

DirectX8 オブジェクトを作成するには、新しいオブジェクトとして宣言する。例を次に示す。

Public gObjDX As New DirectX8

DirectSound8 など、主要な DirectX コンポーネント オブジェクトの多くは、直接作成するのではなく、適切な DirectX8 メソッドを呼び出して作成する必要がある。たとえば、DirectSound8 オブジェクトを作成するには、変数を作成し、その変数に DirectX8.DirectSoundCreate の戻り値を代入する。

Public gObjDSound As DirectSound8
Set gObjDSound = DirectX8.DirectSoundCreate(vbNullString)

次のオブジェクトは、適切な DirectX8 メソッドを呼び出して作成する必要がある。詳細については、「DirectX クラスのリファレンス」を参照すること。

  • Direct3D8
  • DirectInput8
  • DirectMusicComposer8
  • DirectMusicLoader8
  • DirectMusicPerformance8
  • DirectPlay8Address
  • DirectPlay8Client
  • DirectPlay8LobbiedApplication
  • DirectPlay8LobbyClient
  • DirectPlay8Peer
  • DirectPlay8Server
  • DirectPlayVoiceClient8
  • DirectPlayVoiceServer8
  • DirectPlayVoiceTest8
  • DirectSoundCapture8
  • DirectSound8
  • DirectSoundEnum8
  • DirectXFile


GUID の使い方

Microsoft® DirectX® では、オブジェクトの識別などの目的で、グローバル ユニーク識別子 (GUID) を頻繁に使用する。GUID は実際には 128 ビットの整数であるが、通常は {AC330441-9B71-11D2-9AAB-0020781461AC} のように、対応する文字列で表される。

DirectX8 には、特定のプロパティなどのエンティティを識別するために使用される多数の定義済み GUID がある。メソッドに定義済み GUID を渡す必要がある場合、GUID は文字列型 (String) のデータとして処理されるため、文字列形式の GUID を指定する。最も簡単な方法は、文字列エイリアスを使用することである (存在する場合)。たとえば、DirectInput8.CreateDevice メソッドを使用すれば、標準キーボードのデバイスを作成するとき、実際の GUID 文字列ではなく GUID_SysKeyboard で受け渡しをすることが可能である。また、C++ ヘッダー ファイルからコピーアンドペーストするなどして、実際の文字列を使用することもできる。

GUID を作成するには、次の手順を実行する。

  1. DirectX SDK の \Samples\Multimedia\VBSamples\DXMisc\Bin フォルダで Vbguidgen.exe を実行する。
  2. Microsoft Visual Basic® アプリケーションに GUID を貼り付け、引用符で囲む。

DirectX8.CreateNewGuid メソッドを呼び出して実行時に GUID を生成することもできる。


メソッドへの配列の受け渡し

DirectInputDevice8.SendDeviceData など、いくつかの DirectX メソッドでは、型が指定された配列をパラメータとして取る。たとえば、次のコード例で、formatArray は DIDEVICEOBJECTDATA 型の配列である。lCount は配列の要素数を示す。lFlags はデータの送信方法を制御するフラグ パラメータである。

MyDevice.SendDeviceData(lCount, formatArray(), lFlags)

いくつかの DirectX8 メソッドは、Any 型のパラメータを使用してデータを返す。たとえば、DirectSoundCaptureBuffer8.ReadBuffer メソッドの buffer パラメータである。一般には、そのようなメソッドからデータがバイト配列として返されると都合がよい。しかし、Microsoft® Visual Basic® の配列では実データの前に別の情報が含まれているので、単に配列の名前をメソッドに渡すことはできない。配列名の代わりに、配列の最初の要素を渡す必要がある。たとえば、次のコード例で、dsCaptureBuffer は DirectSoundCaptureBuffer8 オブジェクト、nBytes は読み取るバイト数が格納される長整数型 (Long) の値、buffer は 0 ベースのバイト配列である。

ReDim buffer(nBytes)
Call dsCaptureBuffer.ReadBuffer(0, nBytes, buffer(0), 0)


フラグの使い方

Microsoft® DirectX® for Microsoft Visual Basic® の多くのオブジェクト メソッドでは、flags、またはそれに似た名前を持つ長整数型 (Long) のパラメータが使用される。また、型の中にはフラグ メンバを持つものもある。これらの "フラグ フィールド" を使用すると、多数のオプションから簡単に選択できる。多くの場合、フラグ フィールドはメソッドの動作を正確に指定するときに使用される。たとえば、DirectInput8.GetDevicesBySemantics の flags パラメータを使用してオプションの 1 つを選択すると、列挙の範囲を定義できる。

フラグは、はい/いいえを表す 1 ビットの情報である。フラグ フィールドの中で、整数の各ビットは、独立した情報を表す異なるフラグに対応する。ビットを設定した場合、フラグは有効になる。ビットを 0 にした場合、フラグは無効になる。一般に、フラグ フィールドには、列挙により表される一組の関連したフラグが含まれる。通常、列挙の各メンバの数値はフラグ フィールドの異なる 1 ビットを表す。しかし、メンバによっては複数のフラグの組み合わせを表すことがある。

通常、フラグ フィールドを使用すると、さまざまなオプションの 1 つを選択できる。それには、フラグ パラメータに適切な列挙値を代入することが多い。しかし、各フラグは異なるビットに対応するため、フラグ フィールドを使用して、リストから複数のオプションを選択することもできる。それには、Or 演算子を使用し、選択したフラグの列挙値を組み合わせて、関連するビットをすべて設定する。たとえば、DirectInputDevice8.SetCooperativeLevel メソッドには、デバイスの協調レベルの指定に使用されるフラグ フィールドがある。次のコード例では、DISCL_FOREGROUND フラグと DISCL_EXCLUSIVE フラグを組み合わせて、フォアグラウンドと排他協調レベルを選択する。

' diDevice は DirectInputDevice8 オブジェクトで、hwnd はウィンドウ ハンドルである。
diDevice.SetCooperativeLevel(hwnd, _
    DISCL_FOREGROUND Or DISCL_EXCLUSIVE)

注 リファレンス ページをよく調べ、フラグ フィールドの使用方法を確認すること。1 つのフラグしか設定できないフラグ フィールドに複数のフラグを設定すると、予想外の結果が発生することがある。

Or 演算子の代わりに、加算演算子を使用して、フラグを組み合わせないこと。2 つの演算は等価なことが多いが、間違った結果に達することがある。特に、一方のフラグが複数のフラグの組み合わせを表す場合、2 つの演算子は等価ではないことが多い。次の例では、CF_PURPLE フラグは CF_RED と CF_BLUE の組み合わせを表している。

Enum COLORFLAGS
    CF_RED    = 1
    CF_BLUE   = 2
    CF_PURPLE = 3
    CF_GREEN  = 4
End Enum

Dim Color As Integer
Color = CF_RED Or CF_PURPLE

ここで、Color の値は 3 である。CF_RED のビットは CF_PURPLE により既に設定されているため、CF_RED はエフェクトを持たない。

一方、次の演算では不正な値が設定される。

' 次のコードは間違いである。
Color = CF_RED + CF_PURPLE

2 つのフラグの値を加えると、Color は 4 に設定され、CF_GREEN と等価になる。

フラグの値を取得したら、And 演算子を使用してフラグ フィールドのフラグの値を組み合わせ、個々のフラグが設定されているかどうかを確認できる。フラグ フィールドにフラグ定数が表すビットが設定されている場合、And 演算により、フラグが "オン" であることを示す 0 以外の値が返される。And 演算で 0 が返された場合、フラグは "オフ" である。たとえば、DirectInputDevice8.GetCapabilities メソッドの caps パラメータは、デバイスの能力が格納された DIDEVCAPS 型を返す場合に使用される。この型の lFlags メンバは、CONST_DIDEVCAPSFLAGS 列挙セットで指定された 1 つまたは複数のフラグを設定できるフラグ フィールドである。DIDC_ATTACHED フラグが設定された場合、デバイスはシステムに物理的にアタッチされている。次のコード例は、lFlags メンバと DIDC_ATTACHED を組み合わせる And 演算の値を調べることで、デバイスがアタッチされているかどうかを判定する方法を示している。

Dim IsAttached As Boolean
IsAttached = diDevCaps.lFlags And DIDC_ATTACHED

lFlags が DIDC_ATTACHED と等価であるかどうかを単純にテストしてはならない。このフラグ フィールドには、複数のフラグ セットが含まれている可能性がある。複数のフラグが設定されている場合、DIDC_ATTACHED が設定されていても、次のテストは失敗する。

' 次のコードは間違いである。
IsAttached = (diDevCaps.lFlags = DIDC_ATTACHED)


ビットマスクの使い方

D3DCAPS8 など、Microsoft® DirectX® の型の中にはビットマスクとして機能する長整数型 (Long) のメンバを持つものがある。ビットマスクはフラグ フィールドに似ているが、通常はフィールド内の特定のビットをマスクするときに使用される。一般に、対象ビットを判別しやすくするため、16 進形式を使用してビットマスクに値を割り当てる。しかし、Microsoft Visual Basic® は通常 16 進定数を一番短い型に変換しようとするため、エラーが発生することがある。たとえば、&HFF は整数型 (Integer) の値 -1 に変換される。この値が DirectX for Visual Basic に戻されると、長整数型 (Long) の値が予想されているため、&HFFFFFFFF に変換される。

16 進数のビットマスクを適切に変換するには、次のように式の後にアンパサンド (&) をもう 1 つ設定する。例を次に示す。

DDSD.ddpfPixelFormat.lRBitMask = &HFF&


DirectX の列挙

多くの Microsoft® DirectX® アプリケーションでは、通常初期化中に使用可能なリソースを列挙する必要がある。たとえば、DirectX Graphics を使用するアプリケーションでは、使用可能な表示モードを判定する必要がある。また、Microsoft DirectInput® を使用するアプリケーションでは、ジョイスティックで使用可能なボタンや軸を列挙する必要がある。

DirectX for Microsoft Visual Basic® では、アプリケーションは該当する列挙オブジェクトを取得することで列挙を処理する。列挙オブジェクトが作成されると、コレクションが構築される。このコレクションはオブジェクトが存在する限り存在する。アプリケーションでは、列挙オブジェクトのメソッドを使用してコレクションにアクセスできる。

DirectX では、対象タスクが特定された多くの列挙オブジェクトをサポートしている。通常、メソッドを呼び出して列挙オブジェクトを取得する。たとえば、DirectX8 クラスにはそのような 2 つのメソッドがある。その 1 つである DirectX8.GetDSEnum メソッドは、DirectSoundEnum8 列挙オブジェクトを返す。このオブジェクトを使用すると、Microsoft DirectSound® デバイスを列挙し、適切なデバイスの GUID を取得できる。次に、この GUID を使用して、DirectSound8 オブジェクトを作成できる。

さまざまな DirectX コンポーネント オブジェクトから取得される列挙オブジェクトもある。たとえば、DirectInput8.GetDIDevices メソッドを呼び出すと、入力デバイスの列挙オブジェクトを取得できる。

次のサンプル コードは、システムにアタッチされているすべての入力デバイスを列挙する方法を示している。変数 di は、DirectInput8 オブジェクトである。最初に、DirectInputEnumDevices8 列挙オブジェクトを取得する。

Dim diEnum As DirectInputEnumDevices8
Set diEnum = di.GetDIDevices(0, DIEDFL_ATTACHEDONLY)

次に、DirectInputEnumDevices8 メソッドを使用して、アタッチされたデバイスを補間する。各デバイスが必要な特定の能力を持つかどうかを調べる。次の例では、デバイスの名前をリスト ボックスに設定する。

Dim diDevice As DirectInputDeviceInstance
Dim X As Integer

For X = 1 To diEnum.GetCount
    Set diDevice = diEnum.GetItem(X)
    Call List1.AddItem(diDevice.ProductName)
    'デバイスの能力を調べる。
    '...
Next X

注 DirectX の列挙により作成されたコレクションはすべて 1 から始まる。


IUnknown データ型

IUnknown インターフェイスは、すべての COM オブジェクトにより公開される。C++ 開発者はこのインターフェイスを使用して、オブジェクトの機能にアクセスしたりオブジェクトの有効期間を管理できる。Microsoft® Visual Basic® 開発者は、ほとんど IUnknown を利用する必要はない。ただし、Visual Basic では、オブジェクトの IUnknown インターフェイスは IUnknown データ型で表される。

Microsoft DirectX® 8.0 のいくつかの Visual Basic メソッドは、Unknown と宣言された戻り値またはパラメータを備えている。これらの値の型は定義されておらず、IUnknown 型または別のオブジェクト型になる。DirectX 8.0 では、次の 2 つの場合に Unknown 宣言が使用される。

  • オブジェクトがクラスにより表されていない場合。そのようなオブジェクトは、アプリケーションにメソッドまたはプロパティを公開しない。しかし、メソッドからアプリケーションに参照が渡され、その参照がアプリケーションからほかのメソッドに渡されることがある。たとえば、DirectMusicSegment8.GetAudioPathConfig の戻り値は Unknown と宣言される。このメソッドは、クラスでは表されない構成オブジェクトを参照する IUnknown 値を返す。アプリケーションでは、そのオブジェクト参照をほかのメソッドにパラメータとして渡す。
  • パラメータが複数のオブジェクト型を受け取る必要がある場合。パラメータを Unknown として宣言すると、任意のオブジェクト型を受け取ることができる。たとえば、DirectMusicBand8.Unload の最初のパラメータは Unknown と宣言されている。パラメータは、DirectMusicAudioPath8 または DirectMusicPerformance8 のいずれかのオブジェクト参照を受け取ることができる。

    注 Unknown 宣言は Any 宣言に似ている。パラメータまたは戻り値が Any と宣言されている場合、任意のデータ型を渡したり設定できる。同様に、パラメータまたは戻り値が Unknown と宣言されている場合、任意のオブジェクト型を渡したり設定できる。ただし、注意して正しいオブジェクト型を使用しないと、予期しない結果が生じることがある。

変数 IUnknown を使用する場合、オブジェクトのメソッドまたは C++ で使用される QueryInterface、Addref、および Release の各メソッドには直接アクセスできない。変数 IUnknown にオブジェクト参照がある場合、そのオブジェクトのメソッドを使用するには、その変数を適切に宣言されたクラス変数に設定する必要がある。

次のサンプル コードは、IUnknown データ型を使用する方法を示している。

'dmSeg は DirectMusicSegment8 オブジェクトである。
'dmPerf は DirectMusicPerformance8 オブジェクトである。

Dim config as IUnknown
Dim audioPath As DirectMusicAudioPath

Set config = dmSeg.GetAudioPathConfig
Set audioPath = dmPerf.CreateAudioPath(config)

DirectMusicSegment8.GetAudioPathConfig が返す値は、クラスでは表されない構成オブジェクトへの参照である。次に、このオブジェクト参照をほかのメソッド (この場合、DirectMusicPerformance8.CreateAudioPath) に渡す。

次に示す IUnknown データ型の使用方法は間違っている。

'objDiDev は DirectInputDevice8 オブジェクトである。

Dim unk As IUnknown
Set unk = objDiDev
NumItems = unk.GetDeviceData(diDeviceData,0) 'Incorrect!

DirectInputDevice8.GetDeviceData メソッドを呼び出そうとすると、"method not found" エラーが発生する。


エラー処理

Microsoft® Visual Basic® では、メソッド呼び出しは成功するか、失敗するかのいずれかである。呼び出しが失敗した場合、エラーが発生し、Visual Basic の Err グローバル オブジェクトにエラー番号が設定される。その場合、アプリケーションでは、Err オブジェクトを調べるエラー ハンドラに分岐し、エラーに対処する必要がある。さもないと、実行は終了する。しかし、すべての Microsoft DirectX® Visual Basic メソッドの基になる C++ メソッドは、エラーの処理方法が多少異なる。場合によっては、Visual Basic のエラーを解釈するために、C++ の戻り値についての知識が必要になる。

C と C++ では、すべてのメソッド呼び出しで HRESULT 値が返される。この値は、処理の結果を示す、特定の形式を持つ整数である。メソッドで返される HRESULT は、単に処理の成功または失敗を示すこともある。しかし、メソッドによっては、多くの HRESULT 値を使用し、成功と失敗のさまざまなモードを示すこともある。実際、場合によっては、成功を示す複数の戻り値がある。多くの HRESULT 値はシステム標準であり、Winerror.h ヘッダー ファイルに定義されている。通常、システム標準値では成功のコードに S_ プレフィクス、失敗には E_ プレフィクスが使用される。たとえば、成功コードとしては S_OK、失敗コードとして E_FAIL が使用されることが多い。通常 Visual Basic メソッドの基になる C++ コードが標準的な HRESULT 値を返すと、Visual Basic ランタイムによりこの値はトラップされ、Visual Basic の標準エラー コードが設定される。

また、多くの DirectX メソッドでは、1 つまたは複数の標準以外の HRESULT 値がサポートされている。通常、これらの値は列挙で定義されており、各値の意味はメソッドのリファレンスに説明されている。これらの値は標準ではないため、対応する Visual Basic のエラー コードはない。その代わり、Visual Basic ランタイムでは Err.Number をその HRESULT 値に設定する。値の意味については、メソッドのリファレンスを参照すること。HRESULT 値の詳細については、Microsoft Platform Software Development Kit (SDK) の COM のドキュメントを参照すること。


DirectX クラスのリファレンス

ここでは、Microsoft® DirectX® のすべてのコンポーネントに共通する以下のクラスに関するリファレンスを記述する。

  • DirectX8
  • DirectXEvent8


DirectX8

DirectX8 クラスは、Microsoft® DirectX® コンポーネント テクノロジの最初の入口として機能する。このクラスには、さまざまな DirectX コンポーネント用の主要なオブジェクトを作成するメソッド、および多数のコンポーネントで使用されるメソッドが含まれている。通常、このクラスは DirectX アプリケーションで最初に作成されるオブジェクトである。

DirectX8 クラスのメソッドは、以下のグループにまとめることができる。

オブジェクト作成 | Direct3DCreate
 | DirectInputCreate
 | DirectMusicComposerCreate
 | DirectMusicLoaderCreate
 | DirectMusicPerformanceCreate
 | DirectPlayAddressCreate
 | DirectPlayClientCreate
 | DirectPlayLobbiedApplicationCreate
 | DirectPlayLobbyClientCreate
 | DirectPlayPeerCreate
 | DirectPlayServerCreate
 | DirectPlayVoiceClientCreate
 | DirectPlayVoiceServerCreate
 | DirectPlayVoiceSetupCreate
 | DirectSoundCaptureCreate
 | DirectSoundCreate
 | DirectXFileCreate
列挙 | GetDSCaptureEnum
 | GetDSEnum
イベント処理 | CreateEvent
 | DestroyEvent
 | SetEvent
GUID 作成 | CreateNewGuid


DirectX8.CreateEvent

フォームのイベント オブジェクトへのハンドルを作成する。

object.CreateEvent( _
    event As DirectXEvent8 _
) As Long

指定項目

object
DirectX8 オブジェクトを表すオブジェクト式。
event
フォームの DirectXEvent8 オブジェクト。

戻り値

フォームのイベント ハンドルに設定された長整数型 (Long) の値。

エラー コード

失敗した場合はエラーが発生し、Err.Number が設定される。

注意

Microsoft® DirectX® からの通知を受け取るためには、DirectXEvent オブジェクトがフォームにより実装されていなければならない。このメソッドは、DirectXEvent オブジェクトのイベント ハンドルを作成する。このイベント ハンドルは、Microsoft DirectSound®、DirectMusic®、DirectPlay®、および DirectInput® の通知メソッドで使用される。

DirectX は、イベント オブジェクトを、該当するイベントが発生したら信号を送るように自動的に設定する。DirectX8.SetEvent メソッドを使用して、イベントを手動で設定することもできる。通常、これはイベント処理コードをテストするときに行われる。

作成したイベントはすべて、作成元アプリケーションにより DirectX8.DestroyEvent メソッドをを呼び出して明示的に破棄する必要がある。この要件を満たさなければ、予期しない結果が生じることがある。


DirectX8.CreateNewGuid

新しいグローバル ユニーク識別子 (GUID) を生成する。

object.CreateNewGuid() As String

指定項目

object
DirectX8 オブジェクトを表すオブジェクト式。

戻り値

新しい GUID を保持する文字列型 (String) の値。

エラー コード

失敗した場合はエラーが発生し、Err.Number が設定される。


DirectX8.DestroyEvent

DirectX8.CreateEvent メソッドにより作成されたイベント ハンドルを削除する。

object.DestroyEvent( _
    eventid As Long)

指定項目

object
DirectX8 オブジェクトを表すオブジェクト式。
eventid
破棄するイベント ハンドルに設定された長整数型 (Long) の値。DirectX8.CreateEvent を呼び出して作成されたハンドルを使用しなければならない。

エラー コード

失敗した場合はエラーが発生し、Err.Number が設定される。


DirectX8.Direct3DCreate

Direct3D8 オブジェクトを作成する。

object.Direct3DCreate() As Direct3D8

指定項目

object
DirectX8 オブジェクトを表すオブジェクト式。

戻り値

Direct3D8 オブジェクトを返す。

エラー コード

失敗した場合はエラーが発生し、Err.Number が設定される。

注意

この関数は、メモリ不足の場合以外は常に成功する。列挙をサポートする Direct3D8 オブジェクトが作成される。作成された Direct3D8 オブジェクトを使用して、Direct3DDevice8 オブジェクトを作成できる。

このメソッドを呼び出すと、現在アクティブなディスプレイ アダプタ セットがサンプリングされる。ユーザーが、デスクトップにデバイスを追加するか、ラップトップをホットドッキングすることで動的にアダプタを追加した場合、これらのデバイスは、この Direct3D8 オブジェクトの生存期間中には列挙されない。新しい Direct3D8 オブジェクトを作成すると、新しいデバイスが公開される。


DirectX8.DirectInputCreate

DirectInput8 オブジェクトを作成する。

object.DirectInputCreate() As DirectInput8

指定項目

object
DirectX8 オブジェクトを表すオブジェクト式。

戻り値

DirectInput8 オブジェクトを返す。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの Microsoft® DirectInput® エラー コードが設定される。

  • DIERR_BETADIRECTINPUTVERSION
  • DIERR_INVALIDPARAM
  • DIERR_OLDDIRECTINPUTVERSION
  • DIERR_OUTOFMEMORY


DirectX8.DirectMusicComposerCreate

DirectMusicComposer8 オブジェクトを作成する。

object.DirectMusicComposerCreate() As DirectMusicComposer8

指定項目

object
DirectX8 オブジェクトを表すオブジェクト式。

戻り値

DirectMusicComposer8 オブジェクトを返す。

エラー コード

失敗した場合はエラーが発生し、Err.Number が設定される。


DirectX8.DirectMusicLoaderCreate

DirectMusicLoader8 オブジェクトを作成する。

object.DirectMusicLoaderCreate() As DirectMusicLoader8

指定項目

object
DirectX8 オブジェクトを表すオブジェクト式。

戻り値

DirectMusicLoader8 オブジェクトを返す。

エラー コード

失敗した場合はエラーが発生し、Err.Number が設定される。


DirectX8.DirectMusicPerformanceCreate

DirectMusicPerformance8 オブジェクトを作成する。

object.DirectMusicPerformanceCreate() _
    As DirectMusicPerformance8

指定項目

object
DirectX8 オブジェクトを表すオブジェクト式。

戻り値

DirectMusicPerformance8 オブジェクトを返す。

エラー コード

失敗した場合はエラーが発生し、Err.Number が設定される。


DirectX8.DirectPlayAddressCreate

DirectPlay8Address オブジェクトを作成する。

object.DirectPlayAddressCreate() As DirectPlay8Address

指定項目

object
DirectX8 オブジェクトを表すオブジェクト式。

戻り値

DirectPlay8Address オブジェクトを返す。

エラー コード

失敗した場合はエラーが発生し、Err.Number が設定される。


DirectX8.DirectPlayClientCreate

DirectPlay8Client オブジェクトを作成する。

object.DirectPlayClientCreate() As DirectPlay8Client

指定項目

object
DirectX8 オブジェクトを表すオブジェクト式。

戻り値

DirectPlay8Client オブジェクトを返す。

エラー コード

失敗した場合はエラーが発生し、Err.Number が設定される。


DirectX8.DirectPlayLobbiedApplicationCreate

DirectPlay8LobbiedApplication オブジェクトを作成する。

object.DirectPlayLobbiedApplicationCreate() _
    As DirectPlay8LobbiedApplication

指定項目

object
DirectX8 オブジェクトを表すオブジェクト式。

戻り値

DirectPlay8LobbiedApplication オブジェクトを返す。

エラー コード

失敗した場合はエラーが発生し、Err.Number が設定される。


DirectX8.DirectPlayLobbyClientCreate

DirectPlay8LobbyClient オブジェクトを作成する。

object.DirectPlayLobbyClientCreate() _
    As DirectPlay8LobbyClient

指定項目

object
DirectX8 オブジェクトを表すオブジェクト式。

戻り値

DirectPlay8LobbyClient オブジェクトを返す。

エラー コード

失敗した場合はエラーが発生し、Err.Number が設定される。


DirectX8.DirectPlayPeerCreate

DirectPlay8Peer オブジェクトを作成する。

object.DirectPlayPeerCreate() As DirectPlay8Peer

指定項目

object
DirectX8 オブジェクトを表すオブジェクト式。

戻り値

DirectPlay8Peer オブジェクトを返す。

エラー コード

失敗した場合はエラーが発生し、Err.Number が設定される。


DirectX8.DirectPlayServerCreate

DirectPlay8Server オブジェクトを作成する。

object.DirectPlayServerCreate() As DirectPlay8Server

指定項目

object
DirectX8 オブジェクトを表すオブジェクト式。

戻り値

DirectPlay8Server オブジェクトを返す。

エラー コード

失敗した場合はエラーが発生し、Err.Number が設定される。


DirectX8.DirectPlayVoiceClientCreate

DirectPlayVoiceClient8 オブジェクトを作成する。

object.DirectPlayVoiceClientCreate() _
    As DirectPlayVoiceClient8

指定項目

object
DirectX8 オブジェクトを表すオブジェクト式。

戻り値

DirectPlayVoiceClient8 オブジェクトを返す。

エラー コード

失敗した場合はエラーが発生し、Err.Number が設定される。


DirectX8.DirectPlayVoiceServerCreate

DirectPlayVoiceServer8 オブジェクトを作成する。

object.DirectPlayVoiceServerCreate() _
    As DirectPlayVoiceServer8

指定項目

object
DirectX8 オブジェクトを表すオブジェクト式。

戻り値

DirectPlayVoiceServer8 オブジェクトを返す。

エラー コード

失敗した場合はエラーが発生し、Err.Number が設定される。


DirectX8.DirectPlayVoiceSetupCreate

DirectPlayVoiceTest8 オブジェクトを作成する。

object.DirectPlayVoiceSetupCreate() As DirectPlayVoiceSetup8

指定項目

object
DirectX8 オブジェクトを表すオブジェクト式。

戻り値

DirectPlayVoiceSetup8 オブジェクトを返す。

エラー コード

失敗した場合はエラーが発生し、Err.Number が設定される。


DirectX8.DirectSoundCaptureCreate

DirectSoundCapture8 オブジェクトを作成する。

object.DirectSoundCaptureCreate( _
    guid As String _
) As DirectSoundCapture8

指定項目

object
DirectX8 オブジェクトを表すオブジェクト式。
guid
サウンド キャプチャ デバイスを識別する GUID 文字列。このパラメータの値は、DirectX8.getDSCaptureEnum が返した GUID のいずれか、デフォルトのデバイスを指定する vbNullString、または次のいずれかの値でなければならない。
DSDEVID_DEFAULTCAPTURE
システムワイドなデフォルトのオーディオ キャプチャ デバイス。
DSDEVID_DEFAULTVOICECAPTURE
デフォルトの音声キャプチャ デバイス。

戻り値

DirectSoundCapture8 オブジェクトを返す。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの Microsoft® DirectSound® エラー コードが設定される。

  • DSERR_INVALIDPARAM
  • DSERR_NOAGGREGATION
  • DSERR_OUTOFMEMORY

注意

このメソッドは、全二重がサポートされていないサウンド カードの場合は失敗することがある。DirectX8.DirectSoundCreate を呼び出すと、サポートされていないキャプチャ周波数がキャプチャ デバイスに設定され、DirectX8.DirectSoundCaptureCreate が失敗することがある。


DirectX8.DirectSoundCreate

DirectSound8 オブジェクトを作成する。

object.DirectSoundCreate( _
    guid As String _
) As DirectSound8

指定項目

object
DirectX8 オブジェクトを表すオブジェクト式。
guid
サウンド キャプチャ デバイスを識別する GUID 文字列。このパラメータの値は、DirectSoundEnum8.GetGuid が返した GUID のいずれか、デフォルトのデバイスを指定する vbNullString、または次のいずれかの値でなければならない。
DSDEVID_DEFAULTPLAYBACK
システムワイドなデフォルトのオーディオ再生デバイス。
DSDEVID_DEFAULTVOICEPLAYBACK
デフォルトの音声再生デバイス。

戻り値

DirectSound8 オブジェクトを返す。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの Microsoft® DirectSound® エラー コードが設定される。

  • DSERR_ALLOCATED
  • DSERR_INVALIDPARAM
  • DSERR_NOAGGREGATION
  • DSERR_NODRIVER
  • DSERR_OUTOFMEMORY


DirectX8.DirectXFileCreate

DirectXFile オブジェクトを作成する。

object.DirectXFileCreate() As DirectXFile

指定項目

object
DirectX8 オブジェクトを表すオブジェクト式。

戻り値

DirectXFile オブジェクトを返す。

エラー コード

失敗した場合はエラーが発生し、Err.Number が設定される。


DirectX8.GetDSCaptureEnum

DirectSoundEnum8 オブジェクトを作成する。

object.GetDSCaptureEnum() As DirectSoundEnum8

指定項目

object
DirectX8 オブジェクトを表すオブジェクト式。

戻り値

DirectSoundEnum8 オブジェクトを返す。

エラー コード

失敗した場合はエラーが発生し、Err.Number に DSERR_OUTOFMEMORY が設定される。

注意

このメソッドが返す DirectSoundEnum8 オブジェクトは、システムにインストールされている DirectSoundCapture8 オブジェクトの列挙に使用される。

参照

DirectX8.GetDSEnum


DirectX8.GetDSEnum

DirectSoundEnum8 オブジェクトを作成する。

object.GetDSEnum() As DirectSoundEnum8

指定項目

object
DirectX8 オブジェクトを表すオブジェクト式。

戻り値

DirectSoundEnum8 オブジェクトを返す。

エラー コード

失敗した場合はエラーが発生し、Err.Number に DSERR_OUTOFMEMORY が設定される。

注意

このメソッドが返す DirectSoundEnum8 オブジェクトは、システムにインストールされている Microsoft® DirectSound® ドライバの列挙に使用される。

参照

DirectX8.GetDSCaptureEnum


DirectX8.SetEvent

イベント オブジェクトの状態を信号発信済みに設定する。

object.SetEvent( _
    eventid As Long)

指定項目

object
DirectX8 オブジェクトを表すオブジェクト式。
eventid
イベント ハンドルを保持する長整数型 (Long) の値。DirectX8.CreateEvent を呼び出して作成されたハンドルを使用しなければならない。

エラー コード

失敗した場合はエラーが発生し、Err.Number が設定される。

注意

このメソッドは主にテストの目的に使用される。Microsoft® DirectX® は、作成されたすべてのイベント オブジェクトを、該当するイベントが発生したら信号を送るように自動的に設定する。


DirectXEvent8

DirectXEvent8 クラスは、Microsoft® DirectSound®、DirectMusic®、DirectPlay、および DirectInput® で使用されるイベント オブジェクトを作成する。このクラスの目的は、通知イベントを処理するためのコールバック メソッドを提供することにある。DirectXEvent8 オブジェクトは、フォームにクラスを実行することで作成される。

DirectXEvent8 クラスには、DirectXEvent8.DXCallback メソッドがある。


DirectXEvent8.DXCallback

イベント ハンドラへのコールバック ルーチン。

object.DXCallback( _
    eventid As Long)

指定項目

object
DirectXEvent8 オブジェクトを表すオブジェクト式。
eventid
イベント ハンドルを保持する長整数型 (Long) の値。DirectX8.CreateEvent を呼び出して作成されたハンドルを使用しなければならない。

エラー コード

失敗した場合はエラーが発生し、Err.Number が設定される。

注意

フォームに DirectXEvent8 を実装するときは、DirectXEvent.DXCallback メソッドも実装する必要がある。[Object] ボックスの [DirectXEvent8] と [Procedures/Events] ボックスの [DXCallback] をクリックすると、デバッガのウィンドウにメソッドの宣言と終了コードが自動的に設定される。次に、メソッドの形式を示す。

Private Sub DirectXEvent8_DXCallBack(ByVal eventid as Long)
  ' ここにイベント処理コードを記述する。
  .
  .
  .
End Sub

このメソッドに渡すイベント ハンドルは、ユーザーが DirectX8.CreateEvent を使用して作成したものである。

参照

DirectX8.SetEvent


参考資料

Microsoft Windows® プログラミングに関する一般情報、および Microsoft® DirectX® を説明するときに使用したグラフィックスやマルチメディアの概念や用語については、以下の資料を参照すること。

  • Bradley Bargen および Peter Donnelly 著、『Inside DirectX』、Microsoft Press® 社より 1998 年に出版。
  • Durand R. Begault 著、『3-D Sound for Virtual Reality and Multimedia』、Academic Press 社より 1994 年に出版。
  • James Blinn 著、『Jim Blinn's Corner:A Trip Down the Graphics Pipeline』、Morgan Kaufmann 社より 1996 年に出版。
  • Charles Dodge および Thomas A. Jerse 著、『Computer Music:Synthesis, Composition, and Performance』、Schirmer Books 社より 1997 年に出版 (第 2 版)。
  • James D. Foley 著、『Computer Graphics:Principles and Practice』、Addison-Wesley 社より 1991 年に出版 (第 2 版)。
  • Donald Hearn および M. Pauline Baker 著、『Computer Graphics』、Prentice-Hall 社より 1986 年に出版。
  • Tim Kientzle 著、『A Programmer's Guide to Sound』、Addison-Wesley Developers Press 社より 1998 年に出版。
  • Peter J. Kovach 著、『Inside Direct3D』、Microsoft Press 社より 2000 年に出版。
  • Charles Petzold 著、『Programming Windows 98』、Microsoft Press 社より 1998 年に出版 (第 5 版)。
  • Nigel Thompson 著、『3D Graphics Programming for Windows 95』、Microsoft Press 社より 1996 年に出版。
  • Alan H. Watt および Mark Watt 著、『Advanced Animation and Rendering Techniques』、Addison-Wesley 社より 1992 年に出版。

COM に関する概念や用語の詳細については、以下の資料を参照すること。

  • Kraig Brockschmidt 著、『Inside OLE 2』、Microsoft Press 社より 1995 年に出版 (第 2 版)。
  • Dale E. Rogerson 著、『Inside COM』、Microsoft Press 社より 1997 年に出版。


DirectX Graphics

ここでは、Microsoft® DirectX® Graphics アプリケーション プログラミング インターフェイス (API) の使い方について説明する。

DirectX のほかのコンポーネントと同様に、DirectX Graphics は C、C++、および Microsoft Visual Basic® で使用できる。

DirectX Graphics のヘルプの構成については、「ロードマップ」を参照すること。


ロードマップ

Microsoft® DirectX® Graphics については、以下のトピックで説明する。

DirectX Graphics の新機能。DirectX 8.0 のこのコンポーネントの新機能。以前に Microsoft Direct3D® または Microsoft DirectDraw® を使用したことがある場合は、DirectX 7.0 から大幅に変更されているので、最初にこのトピックを読むことを推奨する。

DirectX Graphics の概要。DirectX Graphics およびアプリケーションで実行できる処理の概要と、いくつかの重要なポイントおよび必要な背景情報。

DirectX Graphics について。基本的な構造を詳しく説明する。ここでは、アプリケーションで頂点ライティングやテクスチャ マッピングを実装する方法は説明しないが、詳細を学習する際に API のしくみの理解に役立つはずである。

DirectX Graphics の使い方。API の使い方のガイドである。このトピックの目次を参考にして、特定の情報が必要になったときに対象となる箇所を参照できる。このトピックは、リファレンス トピックと組み合わせて使用すること。

DirectX Graphics の高度なトピック。アプリケーションで DirectX Graphics の能力を最大限に活用するアプリケーションを作成するための情報である。

プログラミングのヒントおよびツール。DirectX Graphics アプリケーションのコンパイル、デバッグ、および最適化に関するさまざまな情報を提供する。また、ここでは、DirectX 8.0 以前のドライバを使用する場合に発生する問題についても説明する。

DirectX Graphics Visual Basic チュートリアル。基本的な機能を段階的に実装するチュートリアルである。実践的に DirectX Graphics を理解することができる。

DirectX Graphics Visual Basic サンプル。必要なサンプル コードを見つけるための、SDK のサンプル アプリケーションについてのガイド。

Direct3D Visual Basic リファレンス。DirectX for Visual Basic 型ライブラリの Direct3D® API 要素について詳しく説明する。

Direct3DX Visual Basic リファレンス。DirectX for Visual Basic 型ライブラリの Direct3DX API 要素について詳しく説明する。

Direct3DX シェーダ アセンブラ リファレンス。Direct3DX 頂点シェーダおよびピクセル シェーダ アセンブラについての詳しいリファレンスである。

エフェクト ファイル形式。エフェクト ファイルのフォーマットに関する情報である。一連のパラメータ宣言およびさまざまなテクニックについての説明で構成される。

X ファイル Visual Basic リファレンス。DirectX for Visual Basic 型ライブラリの DirectX (.x) API 要素について詳しく説明する。

X ファイル フォーマット リファレンス。.x ファイル フォーマットについて詳しく説明する。


DirectX Graphics の新機能

Microsoft® DirectX® 8.0 では、旧リリースの DirectX のオブジェクトとインターフェイスを公開およびサポートすることにより、後方互換性を維持している。ただし、DirectX 8.0 の新しい Microsoft Direct3D® API インターフェイスの一部として、多くの新機能およびパフォーマンスの拡張が追加されている。

DirectDraw と Direct3D の完全な統合
アプリケーションの初期化が簡単になり、データの割り当てと管理のパフォーマンスが向上しており、メモリの使用量が減っている。また、グラフィックス API の統合によって、複数の頂点入力ストリームのパラレル化が可能になり、レンダリングの柔軟性が増している。
プログラム可能な頂点処理言語
カスタム シェーダを作成して、アニメーションのモーフィングやトゥイーニング、行列パレットのスキニング、ユーザー定義のライティング モデル、一般的な環境マッピング、手続きジオメトリ、および開発者が定義するその他のアルゴリズムなどを実現できる。
プログラム可能なピクセル処理言語
カスタム ハードウェア シェーダを作成し、テクスチャを結合する一般的な式、ピクセル単位のライティング (バンプ マッピング)、フォトリアルなスペキュラ エフェクトのためのピクセル単位の環境マッピング、および開発者が定義するその他のアルゴリズムなどを実現できる。
マルチサンプリング レンダリングのサポート
フルスクリーン アンチエイリアシングおよびモーション ブラーや被写界深度などのマルチサンプリング エフェクトが可能になる。
ポイント スプライト
火花、爆発、雨、雪などの粒子システムの高性能レンダリングが可能になる。
3D ボリューム テクスチャ
ピクセル単位のライティングの範囲減衰やボリューム大気エフェクトが可能になり、いっそう複雑なジオメトリに適用できる。
高次プリミティブのサポート
3D コンテンツの外観が向上し、主要な 3D オーサリング ツールからのコンテンツのマッピングが容易になる。
さらに高度なテクノロジ
(さまざまな Direct3D 技法を使って) スキニングされたメッシュを Direct3D にエクスポートするための 3D コンテンツ作成ツール プラグイン、マルチレゾリューションの詳細レベル (LOD) ジオメトリ、高次サーフェス データなど。
インデックス付き頂点ブレンディング
ジオメトリ ブレンディングのサポートが拡張され、頂点ブレンディングに使用する行列を、行列インデックスを使って参照できる。
Direct3DX ユーティリティ ライブラリの拡張
Direct3DX ユーティリティ ライブラリにさまざまな新機能が追加された。Direct3DX ユーティリティ ライブラリは、Direct3D 上のヘルパー層で、3D グラフィックスの開発者が処理しなければならない一般的なタスクを容易にする。スキニング ライブラリ、メッシュの処理のサポート、頂点シェーダやピクセル シェーダをアセンブルするための関数などが含まれる。Microsoft DirectX® 5.0 で最初に導入された D3D_OVERLOADS によって提供されていた機能は、Direct3DX ユーティリティ ライブラリに移動されたことに注意すること。


DirectX Graphics の概要

ここでは、Microsoft® DirectX® Graphics API について紹介し、技術とサービスに関する高度な概要を記述する。

  • DirectX Graphics の機能
  • DirectX Graphics の基礎知識


DirectX Graphics の機能

Microsoft® Direct3D® は、Microsoft Windows® 搭載のコンピュータ上で世界に通用するゲームやインタラクティブ 3D グラフィックスを使えるようにすることを目的に設計されている。3D ビデオディスプレイ ハードウェアへのデバイスに依存したアクセスを、デバイスに依存しない方法で行うことができる描画インターフェイスである。

Direct3D は、ゲームやその他の高性能マルチメディア アプリケーションを Windows オペレーティング システムに移植する必要がある開発者には理想的な下位レベル 3D API である。Direct3D は、アクセラレータ ハードウェアと下位レベルでやり取りするアプリケーションのための方法で、デバイスには依存しない。

Direct3D は、Windows グラフィックス デバイス インターフェイス (GDI) との互換性を維持しながらディスプレイ デバイスへの直接アクセスを提供するソフトウェア デバイスであり、ゲームや 3D グラフィックス パッケージなどの Windows サブシステム ソフトウェアから、特定のディスプレイ デバイスの機能にデバイスに依存しないでアクセスする方法を提供する。

Direct3D は、Windows 95 やそれ以降のバージョン、および Windows 2000 が動作するコンピュータ上に、最上級のゲーム グラフィックスを提供する。

次に示すのは、Direct3D の最新機能である。

  • 切り替え可能な深度バッファリング (Z バッファまたは W バッファを使用)。
  • フラットおよびグーロー シェーディング。
  • 複数の光源とライト タイプ。
  • ミップマッピングなど、マテリアルおよびテクスチャの完全サポート。
  • 強力なソフトウェア エミュレーション ドライバ。
  • トランスフォームとクリッピング。
  • ハードウェア非依存性。
  • Windows 95、Windows 98、Windows ME、および Windows 2000 の完全サポート。
  • Intel の MMX アーキテクチャ、Intel の Streaming Single-Instruction, Multiple-Data (SIMD) Extensions (SSE)®、および AMD® の 3DNow® アーキテクチャ。
  • ハードウェア アブストラクション レイヤ (HAL) のサポート。このサポートによって提供される、ディスプレイ ハードウェアに直接作用する一貫性のあるインターフェイスによって、最大のパフォーマンスを得ることができる。
  • フルスクリーン アプリケーションでの複数のバック バッファによるページ フリッピングのサポート。詳細については、「ページ フリッピングとバック バッファリング」を参照すること。
  • ウィンドウまたはフルスクリーン アプリケーションでのクリッピングのサポート。
  • 3D での Z バッファのサポート。
  • イメージ伸縮ハードウェアへのアクセス。
  • 標準および改良型ディスプレイ デバイス メモリ領域への同時アクセス。
  • その他の機能として、排他的ハードウェア アクセス、および解像度の切り替えなどがある。

これらの機能を組み合わせれば、標準的な Windows GDI ベースのアプリケーションや MS-DOS アプリケーションについて、簡単にその性能を向上させることができる。

Direct3D のワールド管理は、頂点、ポリゴン、およびこれらを制御するコマンドに基づいて行われる。これによって、トランスフォーム、ライティング、ラスタ化 3D グラフィックス パイプラインに直接アクセスできる。ハードウェア アクセラレーションを利用してレンダリングできない場合、Direct3D は強力なソフトウェア エミュレーション機能を提供する。

Direct3D では、シンプルで直接的なメソッドを使用して 3D シーンを設定およびレンダリングできる。レンダリング メソッドの主要セットは DrawPrimitive メソッドと呼ばれる。これらのメソッドにより、アプリケーションではメソッドの呼び出しを 1 回行うだけで、シーンの 1 つまたは複数のオブジェクトをレンダリングできる。これらのメソッドの詳細については、「プリミティブのレンダリング」を参照すること。

Direct3D では、3D ハードウェアへの接続の際に発生するオーバーヘッドが低い。ただし、この接続を実現するためにはかなりの作業を要する。トランスフォームやライティングを実行するには明示的な呼び出しを行わなければならず、必要な行列はすべて提供し、存在するハードウェアの種類やその機能を調べる必要もある。


DirectX Graphics の基礎知識

ここでは、Microsoft® Direct3D® によるグラフィックス プログラミングの概要を説明する。ここで説明する個々の概念は、技術的ではない概要で始まり、DirectDraw がそれをどのようにサポートするかについて多少の具体的説明を加えながら説明する。

ここでの概要を読むにあたっては、グラフィックスの専門家である必要はない。実際、グラフィックスについて詳しい場合は、ここでの説明を読まずに、より詳細なトピックである「DirectX Graphics の使い方」に進んでかまわない。以下のトピックを読み終えれば、基本的な DirectDraw グラフィックス プログラミングの概念を十分に理解することができる。

説明するトピックは、次のとおりである

  • 3D 座標系とジオメトリ
  • シェーディングの技法
  • 行列とトランスフォーム
  • ベクトル、頂点、およびクオータニオン
  • サーフェスのコピー
  • ページ フリッピングとバック バッファリング
  • 矩形


3D 座標系とジオメトリ

Microsoft® Direct3D® アプリケーションをプログラミングするには、3D ジオメトリ原理について理解している必要がある。ここでは、3D シーンの作成において最も重要なジオメトリ原理について説明する。説明するトピックは、次のとおりである。

  • 3D 座標系
  • 3D プリミティブ
  • 三角形ラスタ化ルール

これらのトピックを参照すれば、Direct3D アプリケーションで用いる基本概念について十分に理解できる。これらのトピックの詳細については、「参考資料」を参照すること。


3D 座標系

一般に、3D グラフィックス アプリケーションではデカルト座標系の左手座標系と右手座標系のどちらかを使用する。どちらの座標系でも、x 軸の正方向は右側であり、y 軸の正方向は上方である。z 軸の正方向は、x 軸 の正方向に左手または右手の指を向け、それを y 軸の正の方向に回転した方向になる。親指の方向、手前または奥が、この座標系での z 軸の正方向である。次の図は、これら 2 つの座標システムを示している。

Microsoft® Direct3D® は左手座標系を使用する。右手座標系に基づくアプリケーションを移植する場合は、Direct3D に渡すデータに 2 つの変更を加える必要がある。

  • 三角形の頂点の順序を反転し、システムが前から時計回りにたどれるようにする。つまり、頂点が v0、v1、v2 であるとすると、Direct3D に v0、v2、v1 として渡す。
  • ビュー行列を使用して、ワールド空間を z 軸方向に -1 だけスケーリングする。そのためには、ビュー行列に使用する D3DMATRIX 型の _31、_32、_33、および _34 の各メンバの符号を反転する

右手系に相当する座標系を取得するには、D3DXMatrixPerspectiveRH 関数および D3DXMatrixOrthoRH 関数を使用して、射影トランスフォームを定義する。ただし、対応する D3DXMatrixLookAtRH 関数を使用する場合は、背面カリングの順序を逆にし、その順序でキューブ マップをレイ アウトするよう注意すること。

左手座標系と右手座標系は最もよく使用される座標系システムだが、3D ソフトウェアでは、これらの座標系システム以外にもさまざまな座標系が使用されることがある。たとえば、3D モデリング アプリケーションでは、y 軸がビューアの手前または奥を指し、z 軸が上方を指している座標系が使用されることも珍しくない。この場合、右手座標系は、どの軸 (x、y、または z) の正方向もビューアに近づく方向として定義される。左手座標系は、どの軸 (x、y、または z) の正方向もビューアから離れる方向として定義される。z 軸が上方を指している左手座標系を使用したモデリング アプリケーションを移植する場合は、既に説明した手順に加え、頂点データをすべて回転する必要がある。

3D 座標系で定義されたオブジェクトにおいて重要な操作は、平行移動、回転、およびスケーリングである。これらの基本的なトランスフォームを組み合わせてトランスフォーム行列を作成できる。詳細については、「3D トランスフォーム」を参照すること。

これらの操作を組み合わせるとき、その結果はその操作の順序に依存すること、つまり行列を乗算する順序が重要であることに注意する。


3D プリミティブ

3D プリミティブとは、単一の 3D 構成要素を形成する頂点の集合である。最も単純なプリミティブは、3D 座標系にあるポイントの集合である。これをポイント リストと呼ぶ。

多くの場合、3D プリミティブはポリゴンである。ポリゴンとは、少なくとも 3 つの頂点が結ばれた閉じた 3D 図形である。最も単純なポリゴンは三角形である。三角形の 3 つの頂点はすべて同一平面上にあるため、Microsoft® Direct3D® では三角形を使用してほとんどのポリゴンを形成する。同じ平面上にない頂点のレンダリングは非効率的である。三角形を組み合わせて大きく複雑なポリゴンやメッシュを形成できる。

次の図は立方体を示している。2 つの三角形で立方体の各面が形成されている。三角形の集合全体で 1 つのキューブ プリミティブが形成されている。プリミティブのサーフェスにテクスチャとマテリアルを適用して、プリミティブを単一のソリッド フォームのように表示できる。詳細については、「マテリアル」および「テクスチャ」を参照すること。

また、三角形を使用して、サーフェスが滑らかなカーブのように見えるプリミティブを作成できる。次の図は、三角形で球をシミュレートする方法を示している。マテリアルを適用すると、球はレンダリングしたときに曲面に見える。これは、特にグーロー シェーディングを使用する場合に当てはまる。詳細については、「グーロー シェーディング」を参照すること。


三角形ラスタ化ルール

頂点に指定された点はスクリーン上のピクセルと正確に一致しないことが多い。この場合、Microsoft® Direct3D® は三角形ラスタ化ルールを適用して、どのピクセルが与えられた三角形に当てはまるかを決める。

Direct3D では、ジオメトリを塗りつぶすのに、左上フィリング変換を使用する。この変換は、GDI および OpenGL の矩形に使用する変換と同じである。Direct3D では、ピクセルの中心が重要なポイントである。ピクセルの中心が三角形の内部にある場合、そのピクセルはその三角形の一部である。ピクセルの中心は整数座標にある。

ここで説明する、Direct3D の三角形ラスタ化ルールが、利用可能なすべてのハードウェアに当てはまるとは限らない。現在のハードウェアを調べてみると、このルールの実装において若干の違いが見つかることもある。

次の図は、左上の角が (0, 0) で右下の角が (5, 5) の矩形を示している。この矩形は、予想されるとおり 25 ピクセルを占めている。矩形の幅は、右から左を減算した値で定義される。高さは、下から上を減算した値で定義される。

左上フィリング変換では、上は水平スパンの垂直位置座標を表し、左はあるスパン内のピクセルの水平位置座標を表す。エッジは、水平でない限り上のエッジではありえない。一般に、ほとんどの三角形では左エッジと右エッジがあるだけである。

左上フィリング変換によって、三角形がピクセルの中心を通過するときの Direct3D の処理が決まる。次の図は、頂点が (0, 0)、(5, 0)、(5, 5) の三角形と、頂点が (0, 5)、(0, 0)、(5, 5) の三角形を示している。この場合、前者の三角形は 15 ピクセル (黒で表示) を占めるが、後者の三角形は 10 ピクセル (グレーで表示) しか占めない。共有しているエッジが前者の三角形の左のエッジだからである。

たとえば、左上の角が (0.5, 0.5) で右下の角が (2.5, 4.5) の矩形を定義する場合、この矩形の中心ポイントは (1.5, 2.5) になる。Direct3D ラスタライザでこの矩形をラスタ化すると、各ピクセルの中心は明らかに 4 つの三角形のそれぞれの内部に存在し、左上フィリング変換は不要になる。次の図にこれを示す。矩形内部にあるピクセルには、Direct3D がそのピクセルを入れる三角形に対応したラベルが付けられている。

上の例の矩形を左上の角が (1.0, 1.0)、右下の角が (3.0, 5.0)、中心ポイントが (2.0, 3.0) になるように移動すると、Direct3D は左上フィリング変換を適用する。次の図に示すように、この矩形内部のピクセルのほとんどは、2 つ以上の三角形の間の境界をまたがる。

どちらの矩形でも、同じピクセルが影響を受ける。


シェーディングの技法

ここでは、3D ポリゴンのシェーディングを制御するために Microsoft® Direct3D® で使用する技法について説明する。

  • シェーディング モード
  • シェーディング モードの比較
  • シェーディング モードの設定
  • 面法線ベクトルと頂点法線ベクトル
  • 三角形補間要素


シェーディング モード

ポリゴンのレンダリングに使用するシェーディング モードは、ポリゴンの表示に大きな影響を与える。シェーディング モードによって、ポリゴンの面のポイントの色とライティングの強度が決まる。Microsoft® Direct3D® は、次の 2 つのシェーディング モードをサポートしている。

  • フラット シェーディング
  • グーロー シェーディング


フラット シェーディング

フラット シェーディング モードでは、Direct3D レンダリング パイプラインは、ポリゴンの最初の頂点におけるマテリアルの色をポリゴン全体の色として使用して、ポリゴンをレンダリングする。フラット シェーディングでレンダリングした 3D オブジェクトでは、同一平面上にないポリゴンの間に鋭いエッジが現れる。

次の図は、フラット シェーディングでレンダリングしたティーポットを示している。各ポリゴンの輪郭がはっきりと見える。フラット シェーディングは、計算負荷の最も少ないシェーディングである。


グーロー シェーディング

Microsoft® Direct3D® では、ポリゴンをグーロー シェーディングでレンダリングするとき、頂点の法線パラメータおよびライティング パラメータを使用して各頂点の色を計算する。次に、ポリゴンの面にわたって色を補間する。補間は線形で行われる。たとえば、頂点 1 の色の赤成分が 0.8 で頂点 2 の赤成分が 0.4 の場合、Direct3D のライティング モジュールは、グーロー シェーディング モードおよび RGB カラー モデルを使用して、2 つの頂点の間の線の中間点にあたるピクセルに 0.6 の赤成分を割り当てる。

次の図はグーロー シェーディングを示している。このティーポットは、多数の平坦な三角形のポリゴンで構成されている。しかし、グーロー シェーディングを使用すると、このオブジェクトのサーフェスは滑らかな曲面のようになる。

グーロー シェーディング モードで、鋭いエッジを持つオブジェクトを表示することもできる。

詳細については、「面法線ベクトルと頂点法線ベクトル」を参照すること。


シェーディング モードの比較

フラット シェーディング モードの場合、次のピラミッドは隣接する面の間に鋭いエッジがあるように表示される。ただし、グーロー シェーディングの場合、シェーディング値はエッジ間で補間され、最終的な外観は湾曲サーフェスになる。

グーロー シェーディング モードでは、フラット シェーディング モードの場合よりも、平坦なサーフェスでもよりリアル見える。フラット シェーディング モードの場合、サーフェスの色は一様であるが、グーロー シェーディング モードでは面全体でライティングを適切に弱めることができる。この効果は、近くにポイント光源がある場合に特にはっきりする。

グーロー シェーディングは、フラット シェーディングで現れるポリゴン間の鋭いエッジを滑らかにする。ただし、グーロー シェーディングでは、マッハ バンドが生じる。マッハ バンドとは、隣接するポリゴンで色や光がスムーズにブレンドされていない帯を指す。オブジェクトのポリゴンの数を増やしたり、スクリーン解像度を高めたり、アプリケーションの色深度を上げることで、アプリケーション側でマッハ バンドを減らすことができる。

グーロー シェーディングでは、小さな部分でミスが生じることがある。次の図に例を示す。ここでは、スポット ライトが 1 枚のポリゴンの表面にだけ当てられている。

この場合、グーロー シェーディングが頂点間を補間することからスポット ライトがすべて失われ、まるでスポット ライトが存在しないかのように面がレンダリングされている。


シェーディング モードの設定

Microsoft® Direct3D® では、一度に 1 つのシェーディング モードしか選択できない。デフォルトでは、グーロー シェーディングが選択されている。Microsoft Visual Basic® では、Direct3Ddevice8.SetRenderState メソッドを呼び出してシェーディング モードを変更できる。State パラメータを D3DRS_SHADEMODE に設定する。State パラメータには、CONST_D3DSHADEMODE 列挙のメンバを設定する。次のサンプル コードは、Direct3D アプリケーションの現在のシェーディング モードを、フラット シェーディング モードまたはグーロー シェーディング モードに設定する方法を示している。

'  フラット シェーディングに設定する。
'  このコードでは、d3dDev が Direct3DDevice8 オブジェクトへの
'  有効な参照であるとする。
On Local Error Resume Next
Call d3dDev.SetRenderState(D3DRS_SHADEMODE, _
                           D3DSHADE_FLAT)

' エラーを調べる。
If Err.Number <> D3D_OK Then
    ' エラーを処理する。
End If

' グーロー シェーディングに設定する。これが Direct3D のデフォルト値である。
Call d3dDev.SetRenderState(D3DRS_SHADEMODE, _
                           D3DSHADE_GOURAUD)

If Err.Number <> D3D_OK Then
    ' エラーを処理する。
End If


面法線ベクトルと頂点法線ベクトル

メッシュの各面には、垂直の法線ベクトルがある。法線ベクトルの方向は、頂点が定義されている順序と、座標系が左手座標系か右手座標系かによって決まる。面の法線ベクトルは面の前面から離れる方向に向く。Microsoft®Direct3D® では、面の前面のみ表示される。前面とは、各頂点が時計回りの順に定義された面である。

前面以外の面は背面である。Direct3D では、背面が常にレンダリングされるわけではない。これを背面カリングと言う。カリング モードを変更すれば背面をレンダリングできる。詳細については、「カリング ステート」を参照すること。

Direct3D アプリケーションでは面法線を指定する必要はない。必要なときはシステムで自動的に計算される。システムでは、フラット シェーディング モードで面法線を使用する。グーロー シェーディング モードでは頂点法線を使用する。また、Direct3D はライティング エフェクトとテクスチャ エフェクトの制御にも頂点法線を使用する。

グーロー シェーディングをポリゴンに適用するとき、Direct3D では頂点法線を使用して光源とサーフェス間の角度を計算する。Direct3D では、頂点の色と強度の値を計算し、プリミティブのサーフェス全体のすべてのポイントに対してこの値を補間する。Direct3D では、この角度を使用してライティングの強度の値を計算する。角度が大きいほど、サーフェスを照らす光が弱くなる。

平坦なオブジェクトを作成する場合、次の図に示すように、頂点法線をサーフェスに対して垂直に設定する。2 つの三角形で構成される平坦なサーフェスが定義されている。

しかし、通常はオブジェクトが三角形ストリップで構成され、それらの三角形が同一平面上にないことが多い。ストリップのすべての三角形全体に滑らかなシェーディングを施すには、まず頂点に関係付けられている各ポリゴンのサーフェスについて、面法線ベクトルを計算するのが簡単である。頂点法線は、その周りの各サーフェスの法線からの角度が等しくなるように設定できる。ただし、この方法はプリミティブが複雑な場合には効率的でないことがある。

この方法について次の図で説明する。この図では、S1 と S2 の 2 つのサーフェスがあり、上から見るとエッジが重なっている。S1 と S2 の法線ベクトルは青色で示す。頂点法線ベクトルは赤色で示す。S1 の面法線と頂点法線ベクトルのなす角度は、S2 の面法線と頂点法線のなす角度と同じである。これら 2 つのサーフェスにライトを当て、グーロー シェーディングで陰影を付けると、サーフェス間のエッジの陰影が滑らかになって丸みを帯びる。

頂点法線が、関係付けられているサーフェスのうち 1 つの方へ傾いている場合、光源と面の角度に応じてサーフェス上の点に対する光の強度が増加または減少する。この例を次の図で示す。この図でも、サーフェスのエッジは重なっている。頂点法線は S1 の方に傾いているので、S1 と光源の角度は、頂点法線と 2 つの面法線の角度が等しい場合よりも小さくなる。

グーロー シェーディングを使用して、鋭いエッジのあるオブジェクトを 3D シーンに表示できる。このためには、次の図に示すように、鋭いエッジが必要な、面の交点の位置座標 2 つの頂点でそれぞれの面と同じ法線ベクトルが必要である。

DrawPrimitive メソッドを使用してシーンをレンダリングする場合、エッジが鋭いオブジェクトは、三角形ストリップではなく三角形リストとして定義する。オブジェクトを三角形ストリップとして定義すると、Direct3D ではそのオブジェクトを複数の三角形の面で構成された単一のポリゴンとして扱う。グーロー シェーディングは、ポリゴンの面全体および隣接する面との間の両方に適用される。その結果、オブジェクトの面の境が滑らかにシェーディングされる。三角形リストは、一連の独立した三角形の面から構成されるポリゴンなので、Direct3D ではポリゴンの各面にグーロー シェーディングが適用される。ただし、面と面の境にはグーロー シェーディングは適用されない。三角形リストの複数の三角形が隣接している場合、その三角形の間には鋭いエッジが表示される。

また、エッジが鋭いオブジェクトをレンダリングするとき、フラット シェーディングに変更する方法もある。これはコンピュータには最も効率的であるが、グーロー シェーディングを適用したオブジェクトよりもリアリティに欠けるオブジェクトがシーンに表示される可能性がある。


三角形補間要素

システムでは、面をレンダリングするとき三角形全体で三角形の頂点の特性を補間する。三角形補間要素は次のとおりである。

  • 色
  • スペキュラ
  • アルファ

次の表に示すように、これらの三角形補間要素はすべて、現在のシェーディング モードによって変わる。

シェーディング モード | 説明
フラット | 補間は行われない。その代わり、三角形の最初の頂点の色が面全体に適用される。
グーロー | 線形補間が 3 つの頂点すべての間で実行される。

色補間要素とスペキュラ補間要素の処理はカラー モデルによって異なる。RGB カラー モデルの場合、システムでは赤色、緑色、および青色成分を使用して補間を行う。モノクロ モデル、つまりランプ モデルの場合、システムでは頂点の色の青色成分のみ使用する。

色のアルファ成分は、別の補間要素として扱われる。理由は、テクスチャ ブレンディングと点描の 2 つの異なる方法で、デバイス ドライバが透明化を実行するためである。

D3DCAPS8 型の ShadeCaps メンバを使用して、現在のドライバがサポートしている補間の種類を決定する。


行列とトランスフォーム

Microsoft® Direct3D® の行列を使用して、ワールド トランスフォーム、ビュー トランスフォーム、および射影トランスフォームを定義する。3D グラフィックスのプログラミング未経験者は、ここの内容を学習してプログラムを始めるために重要な概念を理解しておく必要がある。3D プログラミングの経験者は、ここの内容は省略したり、以下のトピックについて簡単に目を通すだけでよい。

  • 行列
  • 3D トランスフォーム


行列

Microsoft® Direct3D® では、行列は 4 × 4 同次行列で表され、D3DMATRIX 型で定義される。

ここでの説明は、ユーザーが Direct3D で作業を行うために十分な行列についての基本的な知識を習得していることを前提としている。詳細については、「3D トランスフォーム」を参照すること。


3D トランスフォーム

Microsoft®Direct3D® では、行列を使用して 3D トランスフォームを行う。ここでは、行列が 3D トランスフォームを作成する方法、トランスフォームによく使用される行列、および行列を組み合わせて複数のトランスフォームを行う単一の行列を生成する方法について説明する。説明するトピックは、次のとおりである。

  • 3D トランスフォームについて
  • 平行移動
  • 回転
  • スケーリング
  • 行列連結

Direct3D でのトランスフォームの詳細については、「Direct3D レンダリング パイプライン」を参照すること。


3D トランスフォームについて

3D グラフィックスを処理するアプリケーションでは、ジオメトリ トランスフォームを使用して次のことができる。

  • オブジェクトの位置座標をほかのオブジェクトとの相対位置座標で表す。
  • オブジェクトを回転、およびサイズを変更する。
  • 位置座標視点、ビュー方向、およびパースペクティブを変更する。

4 × 4 行列を使用すると、任意のポイントを別のポイントにトランスフォームできる。次の例では、行列を使用してポイント (x, y, z) を再度トランスフォームし、新しいポイント (x', y', z') を生成する。

(x, y, z) に対する次の操作と行列を実行してポイント (x', y', z') を生成する。

最も一般的なトランスフォームは、平行移動、回転、およびスケーリングである。これらの効果を生成する行列を組み合わせて単一の行列を作成し、いくつかのトランスフォームを同時に計算できる。たとえば、一連の点を平行移動して回転させる単一の行列を作成できる。詳細については、「行列連結」を参照すること。

行列は、行と列の順序で記述する。頂点を各軸に対して均一にスケーリングする (一様なスケーリングと呼ばれる) 行列は、数学的には次のように表記される。

Microsoft® Visual Basic® の場合、Microsoft Direct3D® では、D3DMATRIX 型を使用して 2 次元配列として宣言された行列を使用する。次の例は、一様なスケーリングを行う行列として機能するように D3DMATRIX 型を初期化する方法を示している。

' この例では、s は Single 型の変数である

Dim ScaleMatrix As D3DMATRIX

    With ScaleMatrix
        .m11 = s
        .m22 = s
        .m33 = s
        .m44 = 1
    End With


平行移動

次のトランスフォームは、ポイント (x, y, z) を新しいポイント (x', y', z') に平行移動する。

Microsoft® Visual Basic® では、独自の平行移動行列を作成できる。次の例は、頂点を平行移動するための行列を作成する関数のソース コードを示している。

Sub TranslateMatrix(m As D3DMATRIX, v As D3DVECTOR)
    D3DXMatrixIdentity m  ' Direct3DX によって実装される。
    m.m41 = v.x
    m.m42 = v.y
    m.m43 = v.z
End Sub

簡便化するため、Direct3DX ユーティリティ ライブラリによって D3DXMatrixTranslation 関数が提供される。


回転

ここでは、左手座標系のトランスフォームについて説明する。したがって、これまでのトランスフォーム行列とは異なる場合もある。詳細については、「3D 座標系」を参照すること。

次のトランスフォームは、ポイント (x, y, z) を x 軸 を中心に回転して新しいポイント (x', y', z') を生成する。

次のトランスフォームは、ポイントを y 軸を中心に回転する。

次のトランスフォームは、ポイントを z 軸を中心に回転する。

これらの行列の例では、ギリシャ文字シータ (θ) は、回転角度をラジアン単位で表している。角度は、回転軸を中心にして原点方向を向いた時計回りで測定したものである。

Microsoft® Visual Basic® アプリケーションでは、Direct3DX ユーティリティ ライブラリによって提供される D3DXMatrixRotationX 関数、D3DXMatrixRotationY 関数、および D3DXMatrixRotationZ 関数を使って回転行列を作成する。

たとえば、x 軸を中心に回転する行列を手動で作成する場合は、次のようなソース コードになる。

Sub CreateXRotation(ret As D3DMATRIX, rads As Single)
    Dim cosine As Single
    Dim sine As Single
    cosine = Cos(rads)
    sine = Sin(rads)

    D3DXMatrixIdentity ret  ' Direct3DX によって実装される。

    ret.m22 = cosine
    ret.m23 = sine
    ret.m32 = -sine
    ret.m33 = cosine
End Sub


スケーリング

次のトランスフォームは、x、y、および z 方向の任意の値でポイント (x, y, z) を新しいポイント (x', y', z') にスケーリングする。


行列連結

行列を使用する利点の 1 つは、複数の行列を乗算してそれらのエフェクトを組み合わせることができるということである。つまり、モデルを回転し、次に別の位置座標に平行移動する場合、2 つの行列を適用する必要はない。その代わり、回転行列と平行移動行列を乗算して、すべてのエフェクトを持つ合成行列を生成する。この処理は行列連結と呼ばれ、次の公式で記述できる。

この公式では、C は作成する合成行列で、M1 ～ Mn は行列 C に含まれる個々のトランスフォームである。ほとんどの場合、2 つまたは 3 つの行列を連結するが、数に制限はない。

D3DXMatrixMultiply 関数を使って、行列の乗算を実行する。

行列の乗算が実行される順序は重要である。上の公式は、行列連結の "左から右" 規則を反映している。つまり、合成行列を作成するために使用する行列の視覚エフェクトは、左から右の順で現われる。一般的なワールド トランスフォーム行列の例を次に示す。お決まりの "空飛ぶ円盤" 用のワールド トランスフォーム行列を作成すると仮定する。この空飛ぶ円盤を中心 (モデル空間 の y 軸) を軸に回転させ、シーン内の別の場所に平行移動したいとする。この効果を実現するには、次の式のように、まず回転行列を作成し、次にこの行列を平行移動行列で乗じる。

この公式では、Ry は y 軸を中心に回転する行列で、Tw はワールド座標の任意の位置座標への平行移動である。

これらの行列を乗算する順序は重要である。2 つのスカラー値を乗算する場合とは異なり、行列の乗算は可換的ではない。平行移動行列と回転行列を逆の順序で乗算すると、空飛ぶ円盤がワールド空間位置座標に移動してから、ワールド座標の原点を中心に回転するというエフェクトが生じてしまう。

どのような行列を作成する場合でも、期待どおりのエフェクトを実現するためには "左から右" 規則を忘れてはならない。


ベクトル、頂点、およびクオータニオン

Microsoft® Direct3D® では、頂点によって位置と向きが表される。プリミティブの各頂点は、位置を示すベクトル、色、テクスチャ座標、および向きを示す法線ベクトルによって記述される。

クオータニオンは、3 コンポーネント ベクトルを定義する [x, y, z] 値に第 4 の要素を追加する。クオータニオンは、3D 回転で一般的に使用される行列メソッドに代わるものである。クオータニオンは、3D 空間内の軸と、その軸を中心とする回転を表す。たとえば、1 つのクオータニオンで軸 (1,1,2) と 1 ラジアンの回転を表すことができる。クオータニオンは重要な情報も伝えるが、その真価は、クオータニオン上で実行できる 2 つの処理、合成と補間で発揮される。

クオータニオンの合成は、結合処理に類似する。2 つのクオータニオンの合成は、以下のように説明することができる。

1 つのジオメトリに対する 2 つのクオータニオンの合成とは、"ジオメトリを axis2 を中心に rotation2 だけ回転した後に、axis1 を中心に rotation1 だけ回転する" ことである。この場合 Q は、ジオメトリに q2 を適用した後に q1 を適用した結果生成された単一軸を中心とする回転を表す。

クオータニオンの補間を使用すれば、アプリケーションはある軸と向きから別の軸と方向までの滑らかで適切なパスを計算することができる。したがって、q1 から q2 の間を補間すれば、ある向きから別の向きへ簡単にアニメーションすることができる。

合成と補間を組み合わせると、ジオメトリの一見複雑そうな操作を簡単に実行できる。たとえば、一定の向きに回転させたいジオメトリがあるとする。axis2 を中心に r2° だけ回転した後に、axis1 を中心に r1° だけ回転することはわかっているが、最終的なクオータニオンはわからないとする。この場合、合成によってジオメトリ上の 2 つの回転を結合すれば、その結果として、単一のクオータニオンが生成される。そして、元のクオータニオンと合成されたクオータニオンの間を補間し、クオータニオンからクオータニオンへ滑らかなトランジションを実現できる。

Direct3DX ユーティリティ ライブラリには、クオータニオンの操作に役立つ関数がある。たとえば、D3DXQuaternionRotationAxis 関数は、回転の軸を定義するベクトルに回転値を加算し、その結果を、D3DQUATERNION 型によって定義されるクオータニオンに返す。さらに、D3DXQuaternionMultiply 関数はクオータニオンを合成し、D3DXQuaternionSlerp は 2 つのクオータニオン間で球状の線形補間を実行する。

Direct3D アプリケーションでは、以下の関数を使ってクオータニオンの操作を単純化することができる。

  • D3DXQuaternionBaryCentric
  • D3DXQuaternionConjugate
  • D3DXQuaternionExp
  • D3DXQuaternionIdentity
  • D3DXQuaternionInverse
  • D3DXQuaternionIsIdentity
  • D3DXQuaternionLength
  • D3DXQuaternionLengthSq
  • D3DXQuaternionLn
  • D3DXQuaternionMultiply
  • D3DXQuaternionNormalize
  • D3DXQuaternionRotationAxis
  • D3DXQuaternionRotationMatrix
  • D3DXQuaternionRotationYawPitchRoll
  • D3DXQuaternionSlerp
  • D3DXQuaternionSquad
  • D3DXQuaternionToAxisAngle

Direct3D アプリケーションでは、以下の関数を使って 3 コンポーネント ベクトルの操作を単純化することができる。

  • D3DXVec3Add
  • D3DXVec3BaryCentric
  • D3DXVec3CatmullRom
  • D3DXVec3Cross
  • D3DXVec3Dot
  • D3DXVec3Hermite
  • D3DXVec3Length
  • D3DXVec3LengthSq
  • D3DXVec3Lerp
  • D3DXVec3Maximize
  • D3DXVec3Minimize
  • D3DXVec3Normalize
  • D3DXVec3Project
  • D3DXVec3Scale
  • D3DXVec3Subtract
  • D3DXVec3Transform
  • D3DXVec3TransformCoord
  • D3DXVec3TransformNormal
  • D3DXVec3Unproject

その他、Direct3DX ユーティリティ ライブラリの算術関数には、2 コンポーネント ベクトルや 4 コンポーネント ベクトルによる処理を単純化するための関数が、多数用意されている。


サーフェスのコピー

このブリット (blit) とは、ビット ブリット (bit block transfer) のことであり、データのブロックをメモリ内のある場所から別の場所に転送するプロセスを指す。ブリットによるデバイス ドライバ インターフェイス (DDI) は、ピクセル数の大きな矩形をフレーム単位で移動する際の主要メカニズム、つまりコピー主体の Direct3DDevice8.Present メソッドの背後にあるメカニズムとして、Microsoft® DirectX® 8.0 でも引き続き使用されている。ブリット処理におけるアートワークの移動は、Direct3DDevice8.UpdateTexture メソッドによって実行される。DirectX 8.0 では、アートワークはピクセルの矩形サブセットをコピーする Direct3DDevice8.CopyRects メソッドを使ってコピーすることもできる。

注 DirectX 8.0 で提供される D3DX 関数によって、アートワークをファイルからロードしたり、色の変更を適用したり、アートワークのサイズを変更したりすることができる。使用できる関数の詳細については、「D3DX8 クラス」のテクスチャのメソッドを参照すること。


ページ フリッピングとバック バッファリング

ページ フリッピングは、マルチメディアやアニメーション、ゲームなどのソフトウェアで主に使用される。ソフトウェア ページ フリッピングは、紙の束を使ってアニメーションを作成する方法に類似する。ページごとに形を少しずつ変えて描画し、紙をすばやくパタパタめくってアニメーションのように見せる方法である。

ソフトウェアでのページ フリッピングは、このプロセスとよく似ている。Microsoft® Direct3D® では、デバイスのプロパティであるスワップ チェーンを介して、ページ フリッピング機能を実装する。最初に、アニメ作家の紙を次のページにフリップするように、スクリーンにフリップする一連の Direct3D バッファをセット アップする。最初のバッファはカラー フロント バッファと呼ばれ、背後のバッファはバックバッファと呼ばれる。アプリケーションはバック バッファに書き込み、次にカラー フロント バッファをフリップしてバック バッファをスクリーンに表示する。システムがイメージを表示している間、ソフトウェアは再びバック バッファに書き込む。このプロセスはアニメーションの間続き、すばやく効率的にイメージをアニメーションさせる。

Direct3D は、比較的単純なダブルバッファ スキーム (1 つのバック バッファを持つカラー フロント バッファ) から、追加のバック バッファを付加したより高度なスキームまで、ページ フリッピング スキームのセット アップを容易にする。


矩形

Microsoft® Direct3D® および Microsoft Windows® プログラミングから、スクリーン上のオブジェクトは境界矩形で参照される。境界矩形の端は常に画面の端と平行であるため、矩形は左上角と右下角の 2 点で記述される。大部分のアプリケーションでは、スクリーンへのブリットやヒット検出を行うために用いられる境界矩形の情報伝達に RECT 構造体が使用される。

Microsoft Visual Basic® における RECT 型の定義を以下に示す。

Type RECT
    Left As Long     ' これは、左上の角の x 座標。
    Top As Long      ' これは、左上の角の y 座標。
    Right As Long    ' これは、右下の角の x 座標。
    Bottom As Long   ' これは、右下の角の y 座標。
End Type

上記の例で、left および top メンバは、境界矩形の左上角の x 座標と y 座標を表す。同様に、right および bottom メンバは、右下角の座標を構成する。次の図は、これらの値を視覚的に説明している。

効率、一貫性、使いやすさなどのために、すべての Direct3D Presentation 関数は矩形範囲を使用する。


DirectX Graphics について

ここでは、Microsoft® DirectX® Graphics の基本的なしくみについて説明する。

  • Direct3D アーキテクチャ
  • Direct3D レンダリング パイプライン


Direct3D アーキテクチャ

ここでは、Microsoft® Direct3D® コンポーネントとその他の Microsoft DirectX® コンポーネント、オペレーティング システム、およびシステム ハードウェアとの関係について説明する。説明するトピックは、次のとおりである

  • Direct3D アーキテクチャの概要
  • ハードウェア アブストラクション レイヤ
  • システムの統合


Direct3D アーキテクチャの概要

Microsoft® Direct3D® アーキテクチャのプログラム可能な部分は、頂点シェーダおよびピクセル シェーダの 2 つである。頂点シェーダは頂点アセンブリの前に呼び出され、頂点を処理する。ピクセル シェーダは DrawPrimitive の呼び出しの後に呼び出され、ピクセルを処理する。

次の単純な図に、Direct3D アーキテクチャを示す。これはアーキテクチャの一部である。Direct3D では 8 つのテクスチャおよびテクスチャ座標をサポートしている。

上の図に示すように、頂点バッファは頂点データを頂点シェーダにストリーミングする。頂点シェーダは、Direct3DX 頂点シェーダ アセンブラによって定義されている命令を使って、ジオメトリ処理を実行する。

頂点シェーダにストリーミングされるデータは、頂点バッファに格納されている必要はないが、格納されていれば理想的である。頂点アセンブリの後で、アセンブルされた頂点データは DrawPrimitive メソッドを使って描画される。この時点で、描画されたプリミティブの各ピクセル (位置、色、テクスチャ、およびテクスチャ座標など) は、ピクセル シェーダに渡される。ピクセル シェーダは、Direct3DX ピクセル シェーダ アセンブラによって定義されている命令を使って、ピクセル処理を実行する。

ピクセルを処理するピクセル シェーダ ステージへの入力には、テクスチャ サーフェスおよびサーフェスのサンプリングを制御する関連するテクスチャ座標が含まれる。出力ピクセルはフレーム バッファに渡される。

Direct3D のプログラム可能な部分のアーキテクチャの詳細については、「頂点シェーダ アーキテクチャ」および「ピクセル シェーダ アーキテクチャ」を参照すること。

頂点シェーダおよびピクセル シェーダをレンダリング パイプラインに組み込む方法の詳細については、「Direct3D レンダリング パイプライン」を参照すること。


頂点シェーダ アーキテクチャ

次の図は、頂点シェーダ アーキテクチャを示している。

頂点データへのデータは、頂点データ ストリームから取得され、定数データは頂点シェーダ宣言子によってロードされる。詳細については、「頂点シェーダ アセンブラ リファレンス」を参照すること。


ピクセル シェーダ アーキテクチャ

次の図は、ピクセル シェーダ アーキテクチャを示している。

ピクセル シェーダへのデータはクリップ空間頂点 (同次座標) である。ディフューズおよびスペキュラ色は、カラー レジスタの値 (v0 および v1) から取得される。テクスチャ座標および設定されたテクスチャは、テクスチャ設定ステージおよび頂点データのテクスチャ レジスタ (t0、t1、t2、および t3) の値から取得される。詳細については、「ピクセル シェーダ アセンブラ リファレンス」を参照すること。


ハードウェア アブストラクション レイヤ

Microsoft® Direct3D® は、ハードウェア アブストラクション レイヤ (HAL) によってデバイスの独立性を提供する。HAL は、デバイス メーカーから提供されるデバイス固有のインターフェイスで、Direct3D はそれを使ってディスプレイ ハードウェアを直接動作させる。アプリケーションは、HAL とは決して相互作用しない。むしろ HAL の提供するインフラを使って、Direct3D はアプリケーションがグラフィックスを表示するために使うインターフェイスやメソッドの一貫したセットを公開する。デバイス メーカーは、Microsoft Windows® のもとでは 16 ビット コード、32 ビット コードの組み合わせで HAL を実装する。Windows NT® および Windows 2000 のもとでは、HAL は常に 32 ビット コードで実装される。HAL は、ディスプレイ ドライバの一部であったり、ドライバの作成者が定義するプライベート インターフェイスからディスプレイ ドライバと通信する個別の DLL になることもできる。

Direct3D HAL は、チップ メーカー、ボード製作者、または OEM 業者により実装される。HAL は、デバイス依存のコードを実装するだけで、エミュレーションは行わない。ある機能がハードウェアにより実行されないとしても、HAL はそれをハードウェア能力と見なして報告しない。さらに、HAL はパラメータを確認しないので、HAL が起動される前に Direct3D がこのパラメータを確認する。

DirectX 8.0 では、HAL は 3 種類の頂点処理モードを持つことができる。ソフトウェア頂点処理、ハードウェア頂点処理、および同一デバイスでの混合頂点処理である。ピュア デバイス タイプは HAL デバイスの一種である。ピュア デバイス タイプはハードウェアによる頂点処理のみをサポートし、アプリケーションが照会できるのはデバイス ステートの小さなサブセットに限られる。さらに、ピュア デバイスは、最小レベルの能力を備えたアダプタでのみ使用できる。


システムの統合

次の図は、Microsoft® Direct3D® と、グラフィックス デバイス インターフェイス (GDI)、ハードウェア アブストラクション レイヤ (HAL)、およびハードウェアとの関係を示している。

前の図に示すように、Direct3D アプリケーションは GDI アプリケーションと共に存在し、これらはグラフィックス カード用のデバイス ドライバを介してグラフィックス ハードウェアにアクセスする。GDI とは異なり、Direct3D は、HAL デバイスが選択されているときにハードウェア機能を利用できる。HAL デバイスは、グラフィックス カードでサポートされる機能セットに基づいて、ハードウェア アクセラレーションを提供する。デバイスにタスクの能力があるかどうかを実行時に判断するための Direct3D メソッドを利用できる。

ソフトウェア デバイスは、DirectX 8.0 機能セット全体をサポートしているわけではないが、アプリケーションが常に、どのシステムにおいても、動作しているデバイスを見つけることができるようにしている。ただし、多くの場合、ソフトウェア デバイス上で実行されるアプリケーションでは、低下した機能でも実行されるように準備する必要がある。ソフトウェア デバイスの能力は、ハードウェア デバイスの能力と同じ方法で調べることができる。

Direct3D でサポートされるデバイスの詳細については、「デバイスの種類」を参照すること。


Direct3D レンダリング パイプライン

Microsoft® Direct3D® レンダリング パイプラインは、頂点トランスフォームおよびライティング パイプライン、およびピクセルおよびテクスチャ ブレンディング パイプラインの動作を指定する一連の処理ステージである。

3D アプリケーションを設計するとき、利便性を考慮してミクロンからパーセクまで、あらゆる単位でワールドを定義できる。アプリケーションは、このワールドの記述を Direct3D に渡す。この記述には、ワールド内にあるすべてのオブジェクトのサイズと相対位置座標、およびビューアの位置座標と向きが含まれる。Direct3D は、この記述 (頂点) をスクリーン上の一連のピクセルに変換する。この処理の最初のステップ (ジオメトリの 2D 画像への変換) のことを、ジオメトリ パイプラインまたはトランスフォーム パイプラインと呼ぶ。頂点を処理した後、ピクセル データを使ってマルチテクスチャ処理およびフォグ ブレンディングが実行される。次に、アルファ、ステンシル、および深度テストが実行される。最後に、フレームバッファ ブレンディングがラスタライザによって実行される。

以下のトピックでは、主に Direct3D における完全なレンダリング パイプラインについて説明する。また、重要な概念について、およびこれらの概念に対応する Direct3D API の概念についても解説する。固定機能処理のトピックでは、旧バージョンの Microsoft DirectX® を使用していた開発者であれば既に理解している手法について説明する。したがって、プログラム可能 (プロシージャ) 処理のトピックでは、Microsoft DirectX 8.0 の頂点処理とピクセル処理で使用される新しいプロシージャ モデルについて説明する。

  • 固定機能による頂点処理とピクセル処理
  • プログラム可能な頂点処理とピクセル処理
  • 頂点プロセッサへの頂点データの提示


固定機能による頂点処理とピクセル処理

ジオメトリの固定機能によるジオメトリ パイプラインを実行するのは、Microsoft® Direct3D® のトランスフォーム エンジンである。これは、ワールド内のモデルとビューアを検出し、スクリーン上に表示できるように頂点を射影し、頂点をビューポートに切り取る。また、トランスフォーム エンジンは、ライティング計算を実行して各頂点のディフューズおよびスペキュラ成分を決定する。

ジオメトリ パイプラインは、頂点を入力として受け取る。トランスフォーム エンジンは、頂点に 3 つのトランスフォーム (ワールド トランスフォーム、ビュー トランスフォーム、および射影トランスフォーム) を適用し、結果をクリップして、そのすべてをラスタライザに渡す。次の図は、一連のステップを示している。

パイプラインの最初の段階においてはトランスフォームは適用されず、モデルの頂点はすべてローカル座標系 (これはローカル原点と向きである) に対して宣言される。この座標向きを一般にモデル空間と呼び、個々のローカル座標はモデル座標と呼ぶ。

ジオメトリ パイプラインでは、最初にローカル座標系のモデルの頂点が、シーンのすべてのオブジェクトで使用する座標系にトランスフォームされる。頂点をワールド座標系で再度定義し直すことを、ワールド トランスフォームと呼ぶ。この新しい向きは、通常はワールド空間と呼ばれ、ワールド空間の各頂点は、ワールド座標を使用して宣言される。

次に、3D ワールドを記述する頂点をカメラに対する相対位置座標で定義し直す。つまり、アプリケーションはシーンの視点 (カメラの位置) を選択し、ワールド空間は視点の位置と向きに合わせて再定義される。すなわち、ワールド空間がカメラ空間にトランスフォームされる。これがビュー トランスフォームである。

次の段階では、射影トランスフォームが行われる。パイプラインにおけるこの段階では、通常、遠くのオブジェクトよりも近くのオブジェクトの方が大きく見えるようにするなど、ビューアからの距離を基準にオブジェクトがスケーリングされて、シーンに奥行きが生まれる。わかりやすくするために、このドキュメントでは、射影トランスフォーム後の頂点が存在する空間を、射影空間と呼ぶことにする。グラフィックス関連の書籍では、射影空間のことを、遠近補正後同次空間と呼ぶ場合もある。すべての射影トランスフォームによってシーンのオブジェクトのサイズがスケーリングされるとは限らない。このような射影は、アフィン射影または正射影と呼ばれることもある。

パイプラインの最後の段階では、スクリーン上で見えない頂点がすべて削除される。これにより、ラスタライザは、見えないオブジェクトに関して色とシェーディングの計算を実行する必要がなくなる。この処理はクリッピングと呼ばれる。クリッピングが完了すると、残りの頂点はビューポート パラメータに従ってスケーリングされ、スクリーン座標系にトランスフォームされる。その結果、これらの頂点は、シーンがラスタ化されたときにスクリーンに表示され、スクリーン空間に存在するようになる。

固定頂点処理とピクセル処理パイプラインについては、以下のトピックに分けて説明する。

  • トランスフォームおよびライティング エンジン
  • ビューポートとクリッピング
  • ラスタ化


トランスフォームおよびライティング エンジン

以下のトピックでは、固定機能によるトランスフォームおよびライティング エンジンの各コンポーネントのしくみを詳しく説明する。

  • ワールド トランスフォーム
  • ビュー トランスフォーム
  • 射影トランスフォーム
  • ライティング エンジン
  • Direct3D のライティングにおける数学的計算


ワールド トランスフォーム

ここでは、ワールド トランスフォームについての基本的な概念を紹介し、Microsoft® Direct3D® アプリケーションでワールド トランスフォーム行列を設定する方法について詳しく説明する。説明するトピックは次のとおりである。

  • ワールド トランスフォームとは
  • ワールド行列の設定


ワールド トランスフォームとは

ワールド トランスフォームでは、頂点がモデルのローカル原点に対して定義されるモデル空間から、頂点がシーン内のすべてのオブジェクトに共通する原点に対して定義されるワールド空間に座標をトランスフォームする。基本的には、ワールド トランスフォームによってモデルがワールドに配置されることから、このような名前が付いている。次の図は、ワールド座標系とモデルのローカル座標系の関係を示している。

ワールド トランスフォームでは、平行移動、回転、およびスケーリングをどのように組み合わせても使用できる。トランスフォームの数学上の説明については、「3D トランスフォーム」を参照すること。


ワールド行列の設定

ほかのすべてのトランスフォームと同様、一連のトランスフォーム行列を、個々の効果をすべて含む単一の行列に連結することでワールド トランスフォームを作成する。簡単な例では、あるモデルがワールド原点にあり、そのローカル座標軸がワールド空間と同じ方向に定義されている場合、ワールド行列は単位行列である。さらに一般的には、ワールド行列はワールド空間への平行移動を組み合わせたものであり、必要に応じてモデルを 1 回または何度も回転することができる。

次の例は、Microsoft Visual Basic で記述された架空の 3D モデル クラスに関するものである。ここでは、Direct3DX ユーティリティ ライブラリに含まれるヘルパー関数を使用して、モデルを方向付ける回転を 3 回行い、ワールド空間での位置座標を基準にそのモデルを再配置する平行移動を行うワールド行列を作成する。

'
' この例では、次の変数は
' 有効であり、初期化されていると仮定する。
'
'   変数 m_xPos、m_yPos、m_zPos はモデルの
'   ワールド座標での位置を格納する。
'
'   変数 m_sPitch、m_sYaw、および m_sRoll は Single で、
'   ピッチ、ヨー、およびロール (ラジアン単位) での
'   モデルの向きを格納する。
'
Public Function MakeWorldMatrix() As D3DMATRIX
    Dim matWorld As D3DMATRIX   ' 返されるワールド行列。
    Dim matTemp As D3DMATRIX    ' 回転を保持するテンポラリ行列。
    Dim matRot As D3DMATRIX     ' テンポラリ回転行列。

    ' matWorld を変更して平行移動行列を作成する。
    D3DXMatrixIdentity matWorld
    matWorld.m41 = m_xPos
    matWorld.m42 = m_yPos
    matWorld.m43 = m_zPos

    D3DXMatrixIdentity matRot ' 回転行列を設定する。

    '
    ' 左から右に行列を連結して、
    ' オブジェクトのワールド位置座標に平行移動を適用した後、
    ' 回転を適用する。
    '

    ' 回転行列を作成し、組み合わせる。
    If (m_sPitch <> 0) Or (m_sYaw <> 0) Or (m_sRoll <> 0) Then
       ' 最初に、ピッチ。
        D3DXMatrixRotationX matTemp, m_sPitch
        D3DXMatrixMultiply matRot, matRot, matTemp

       ' 次に、ヨー。
        D3DXMatrixRotationY matTemp, m_sYaw
        D3DXMatrixMultiply matRot, matRot, matTemp

        ' 最後に、ロール。
        D3DXMatrixRotationZ matTemp, m_sRoll
        D3DXMatrixMultiply matRot, matRot, matTemp

        ' 回転行列を、既に matWorld に存在する平行移動に
        ' 適用し、ワールド行列を完成する。
        D3DXMatrixMultiply matWorld, matRot, matWorld
    End If

    MakeWorldMatrix = matWorld
End Function

ワールド トランスフォーム行列が準備できたら、この行列を設定するために Direct3DDevice8.SetTransform メソッドを呼び出して、第 1 パラメータに D3DTS_WORLD フラグを指定する。詳細については、「トランスフォームの設定」を参照すること。

注 Microsoft® Direct3D® では、設定されたワールド行列およびビュー行列を使用して、いくつかの内部データ構造を構築する。新しいワールド行列またはビュー行列を設定するたびに、関係する内部構造が再計算される。これらの行列をフレームごとに数千回も設定するなど頻繁に設定すると、多大な計算負荷が発生する。必要な計算を最小限に抑えるには、ワールド行列として設定するワールドビュー行列にワールド行列およびビュー行列を連結した後、ビュー行列を単位行列に設定する。必要に応じてワールド行列を修正、連結、およびリセットできるように、ワールド行列およびビュー行列の各キャッシュ コピーは保持しておくこと。このドキュメントの Direct3D のサンプルでは、簡潔であることを優先して、この最適化はほとんど用いていない。


ビュー トランスフォーム

ここでは、ビュー トランスフォームの基本的な概念を紹介し、Microsoft® Direct3D® アプリケーションでビュー トランスフォーム行列を設定する方法について詳しく説明する。説明するトピックは、次のとおりである。

  • ビュー トランスフォームとは
  • ビュー行列の設定


ビュー トランスフォームとは

ビュー トランスフォームとは、ワールド空間に視点を配置し、頂点をカメラ空間にトランスフォームする処理である。カメラ空間では、カメラ (つまり視点) は原点にあり、ｚ 軸の正方向を向く。Microsoft® Direct3D® では左手座標系を使用するため、z はシーンの正方向を向く。ビュー行列は、ワールド内のオブジェクトをカメラの位置 (カメラ空間の原点) と向きの周囲に再配置する。

ビュー行列は多くの方法で作成できる。すべての方法において、カメラはワールド空間内でいくつかの論理位置座標と向きを持つ。これらの位置座標と方向は、シーン内のモデルに適用するビュー行列を作成する際の始点となる。ビュー行列は、オブジェクトを平行移動および回転して、カメラを原点としたカメラ空間内に位置座標付ける。ビュー行列を作成する方法としては、平行移動行列と各軸に対する回転行列を組み合わせる方法がある。この方法では、次の一般的な行列式が適用される。

この式では、V は作成するビュー行列、T はオブジェクトをワールド内に再配置する平行移動行列、Rx ～ Rz は x、y、および z 軸に沿ってオブジェクトを回転する回転行列である。この平行移動行列と回転行列は、ワールド空間におけるカメラの論理位置座標と向きに基づいている。したがって、ワールドにおいてカメラの論理位置座標が <10,20,100> の場合、平行移動行列は、x 軸に沿って -10 単位、y 軸に沿って -20 単位、z 軸に沿って -100 単位だけオブジェクトを平行移動することになる。この式における回転行列は、カメラの向きに基づいており、カメラ空間の軸がワールド空間からどれくらい回転するかを表す。たとえば、上の例のカメラが真下を向いている場合、次の図に示すように、カメラ空間の z 軸はワールド空間の z 軸から 90° (π/2 ラジアン) だけずれている。

回転行列は、マグニチュードは同じであるが方向が逆の回転を、シーン内のモデルに適用する。このカメラに対するビュー行列は、x 軸を中心とした -90°の回転を含む。回転行列と平行移動行列を組み合わせることで、シーン内のオブジェクトの位置座標と向きを調整するビュー行列を作成して、オブジェクトの上側にカメラを置いてモデルを上から見下ろすことができる。

別の方法として、複雑なビュー行列を直接作成する方法もある。D3DXMatrixLookAtRH および D3DXMatrixLookAtRH メンバでは、この手法が使用される。この方法では、カメラのワールド空間における位置座標とシーン内の注視点を使用して、カメラ空間の座標軸の向きを記述するベクトルを派生させる。注視点からカメラ位置座標を減算して、カメラの方向ベクトル (ベクトル n) 用のベクトルを生成する。次に、ベクトル n とワールド空間の y 軸の外積をとり、正規化して、右方向ベクトル (ベクトル u) を生成する。次に、ベクトル u と n の外積をとり、上方向ベクトル (ベクトル v) を決める。右方向 (u)、上方向 (v)、およびビュー方向 (n) のベクトルは、ワールド空間におけるカメラ空間の座標軸の向きを記述する。x、y、z の平行移動係数は、カメラ位置座標と u、v、n ベクトルの間の内積の負数をとって計算する。

これらの値を次の行列に入れて、ビュー行列を生成する。

この行列では、u、v、n はそれぞれ上方向、右方向、ビュー方向のベクトルであり、c はカメラのワールド空間位置座標である。この行列には、ワールド空間をカメラ空間に平行移動と回転するために必要な要素がすべて格納される。この行列を作成した後、z 軸を中心とする回転行列を作成して、カメラを回転することができる。

この方法の実装については、「ビュー行列の設定」を参照すること。


ビュー行列の設定

Microsoft® Visual Basic® アプリケーションでは、D3DXMatrixLookAtLH および D3DXMatrixLookAtRH ヘルパー関数を使用して、カメラ位置座標、注視点、上方向ベクトル (通常は 0,1,0) に基づいてビュー行列を作成する。

次の Visual Basic コードは、D3DXMatrixLookAtLH 関数の使用方法を示している。

    ' この例では、g_D3DDevice は Direct3DDevice8 オブジェクトへの
    ' 有効な参照であると仮定している。

    Dim matView As D3DMATRIX

    ' 視点を z 軸方向に 5 単位後ろ、
    ' 3 単位上に設定する。
    D3DXMatrixLookAtLH matView, vec3(0#, 3#, -5#), _
                                 vec3(0#, 0#, 0#), _
                                 vec3(0#, 1#, 0#)

    g_D3DDevice.SetTransform D3DTS_VIEW, matView

ワールド トランスフォームの場合と同様、Direct3DDevice8::SetTransform メソッドを呼び出してビュー トランスフォームを設定し、第 1 パラメータに D3DTS_VIEW フラグを指定する。詳細については、「トランスフォームの設定」を参照すること。

パフォーマンスの最適化に関する注 Microsoft® Direct3D® では、設定されたワールド行列およびビュー行列を使用して、いくつかの内部データ構造を構築する。新しいワールド行列またはビュー行列を設定するたびに、関係する内部構造が再計算される。これらの行列をフレームごとに 20,000 回も設定するなど頻繁に設定すると、多大な計算負荷が発生する。必要な計算を最小限に抑えるには、ワールド行列として設定するワールドビュー行列にワールド行列およびビュー行列を連結した後、ビュー行列を単位行列に設定する。ワールド行列およびビュー行列の各キャッシュ コピーは保持しておくこと。必要に応じてワールド行列を修正、連結、およびリセットできる。Direct3D のサンプルでは、簡潔であることを優先して、この最適化はほとんど用いていない。


射影トランスフォーム

射影トランスフォームは、カメラの内部を制御することと考えることができる。つまり、射影トランスフォームは、カメラのレンズを選ぶことに似ている。このトランスフォームは、3 種類のトランスフォームの中で最も複雑である。射影トランスフォームについては、以下のトピックに分けて説明する。

  • 視錐台
  • 射影トランスフォームとは
  • 射影行列の設定
  • W バッファに有効な射影行列


視錐台

視錐台とは、ビューポートのカメラに対して相対的に配置されたシーン内の 3D 立体である。この立体の形は、カメラ空間からスクリーンにモデルを射影する方法に影響を与える。最も一般的な射影は、パースペクティブ射影である。この射影では、カメラの近くにあるオブジェクトが、カメラの遠くにあるオブジェクトよりも大きく表示される。パースペクティブ ビューの場合、視錐台とは先端にカメラがあるピラミッドと考えるとわかりやすい。このピラミッドは、前方および後方クリップ面に当たる。前方および後方クリップ面の間にあるピラミッド内の立体が視錐台である。オブジェクトは、この立体内にあるときにのみ見ることができる。

視錐台は、暗い部屋の中で正方形の窓から外を見ている状況を想像するとわかりやすい。別な表現をすると、前方クリップ面は窓であり、後方クリップ面は視界を最終的に遮るもの、たとえば、街の高層ビル、遠方の山脈、または完全な無の空間である。視錐台の内部 (窓から最終的に遮るものまでの間) にあるものはすべて見ることができ、それ以外のものは見ることができない。

視錐台は、z 座標で指定される前方および後方クリップ面の間の距離と FOV (視野) で定義される。

この図では、変数 D は、カメラから、ジオメトリ パイプラインの最後の部分 (ビュー トランスフォーム) で定義された空間の原点までの距離である。この空間の周りに視錐台の限界を設定する。この変数 D を使用して射影行列を作成する方法については、「射影トランスフォームとは」を参照すること。


射影トランスフォームとは

射影行列とは、一般に、スケーリング パースペクティブ射影である。射影トランスフォームでは視錐台を立方体にトランスフォームする。視錐台の近くの端は遠くの端よりも小さいので、このトランスフォームにはカメラの近くのオブジェクトを拡大するという効果があり、これによってシーンに遠近感が生まれる。

視錐台では、射影トランスフォームに必要なカメラとビュー トランスフォームによって定義される空間の原点の間の距離が、D として定義される。パースペクティブ射影を定義する行列では、次のように、最初にこの変数 D を使用する。

ビュー行列は、カメラをシーンの原点に配置する。射影行列では (0, 0, -D) にカメラを配置する必要があるので、射影行列は次の行列を使用してベクトルを z 方向に -D だけ平行移動する。

これら 2 つの行列を乗算すると、次のような合成行列ができる。

次の図は、パースペクティブ トランスフォームが視錐台を新しい座標空間に変換する方法を示している。視錐台が立方体になること、およびシーンの右上角にあった原点が中心に移動することに注目する。

パースペクティブ トランスフォームでは、x 方向と y 方向の限界は -1 と 1 である。z 方向の限界は、前方面ついては 0 で、後方面については 1 である。

この行列は、カメラから前方のクリップ面までの距離に基づいてオブジェクトを平行移動およびスケーリングする。しかし、この行列は視野 (FOV) を考慮せず、遠くのオブジェクトに対して生成する z 値はほとんど同じなので、深度比較が困難になる。この問題を解決するために、次の行列は、ビューポートのアスペクト比を考慮して頂点を調整し、アスペクト比をパースペクティブ射影に合わせる。

この行列では、Zn は前方のクリップ面の z 値である。変数 w、h、および Q の意味は、次のとおりである。FOVw および FOVh は、ビューポートの水平方向および垂直方向の視野を表す (ラジアン単位)。

アプリケーションでは、視野角度を使用して x と y の倍率を定義することは、ビューポートの水平寸法と垂直寸法 (カメラ空間の) を使用するのに比べて不便な場合がある。数学の練習問題として、次に示す w と h 用の 2 つの式ではビューポートの寸法を使用している。これらの式は上の公式と同等である。

これらの式では、Zn は前方のクリップ面の位置座標を表し、変数 Vw と Vh はカメラ空間でのビューポートの幅と高さを表している。

Microsoft® Visual Basic® アプリケーションでは、幅と高さの寸法は、D3DVIEWPORT8 型の Width および Height メンバに直接対応する。

どの式を使用する場合でも、Zn をできるだけ大きな値に設定することが重要である。理由は、カメラに極端に近い z 値は大幅には変化しないため、16 ビットの z バッファを使用する深度比較が困難になるからである。

ワールド トランスフォームおよびビュー トランスフォームと同様、Direct3DDevice8.SetTransform メソッドを使用して射影トランスフォームを設定する。詳細については、「トランスフォームの設定」を参照すること。


射影行列の設定

Microsoft® Visual Basic® で記述されたアプリケーションでは、射影行列を作成できる。これについては、「射影トランスフォームとは」で説明する。ただし、Direct3DX ユーティリティ ライブラリには、射影行列を設定するための次の関数が用意されている。

  • D3DXMatrixPerspectiveLH
  • D3DXMatrixPerspectiveRH
  • D3DXMatrixPerspectiveFovLH
  • D3DXMatrixPerspectiveFovRH
  • D3DXMatrixPerspectiveOffCenterLH
  • D3DXMatrixPerspectiveOffCenterRH

次の Visual Basic コードは、D3DXMatrixPerspectiveLH の一般的な使用方法を示している。

    ' この例では、g_D3DDevice は Direct3DDevice8 オブジェクトへの
    ' 有効な参照であると仮定している。

    ' 射影行列では、パースペクティブ トランスフォームを設定する。
    ' これは、ジオメトリを 3D ビュー空間から 2D ビューポート空間にトランスフォームし、
    ' パースペクティブ分割を行うことで、
    ' 遠方のオブジェクトを小さくする。パースペクティブ トランスフォームを作成するには、
    ' 視野 (通常は 1/4 π)、アスペクト比、
    ' および近くと遠方のクリップ面
    ' (ジオメトリがレンダリングされなくなる距離を定義する) が必要である。

    Dim matProj As D3DMATRIX

    D3DXMatrixPerspectiveFovLH matProj, g_pi / 4, 1, 1, 1000
    g_D3DDevice.SetTransform D3DTS_PROJECTION, matProj

行列を作成した後は、Direct3DDevice8.SetTransform メソッドを呼び出してその行列を設定し、第 1 パラメータに D3DTRANSFORMSTATE_PROJECTION を指定する必要がある。詳細については、「トランスフォームの設定」を参照すること。


W バッファに有効な射影行列

Microsoft® Direct3D® では、ワールド行列、ビュー行列、および射影行列によってトランスフォームされた頂点の W 要素を利用して、深度バッファまたはフォグ エフェクトの計算を深度をベースに実行できる。このような計算では、射影行列により W をワールド空間 Z で対応する W に正規化する必要がある。つまり、射影行列に 1 ではない (3,4) 係数が含まれる場合、(3,4) 係数の逆数を使用してすべての係数をスケーリングすることで、適切な行列を作成しなければならない。対応していない行列を使用すると、フォグ エフェクトと深度バッファが正しく適用されない。射影トランスフォームとはで推奨する射影行列は、w ベースの計算に対応している。

次の図は、対応していない射影行列、および同じ行列をスケーリングして視点との相対フォグが有効になるようにした行列を示している。

上の図では、すべての変数がゼロ以外の値であるとする。視点との相対フォグの詳細については、「視点からの相対深度 対 Z ベースの深度」を参照すること。w ベースの深度バッファリングについては、「深度バッファとは」を参照すること。

注 Direct3D では、現在設定されている射影行列が w ベースの深度計算に使用される。したがって、アプリケーションで Direct3D トランスフォーム パイプラインを使用しない場合であっても、希望の w ベース機能を取得するために適切な射影行列を設定しておく必要がある。


ライティング エンジン

ここでは、Microsoft® Direct3D® ライティング エンジンの概要について説明する。説明するトピックは、次のとおりである

  • ライティング エンジンの有効/無効
  • ライトのカラー タイプとソース
  • フォグ エフェクト

ライティング エンジンの内部動作の詳細については、「Direct3D のライティングにおける数学的計算」を参照すること。


ライティング エンジンの有効/無効

デフォルトでは、Microsoft® Direct3D® は、すべての頂点に対してライティング計算を実行する。この計算は、頂点法線を持たない頂点に対しても実行される。ただし、D3DRS_LIGHTING レンダリング ステートを使用してライティングを無効にできる。Direct3DDevice8.SetRenderState メソッドを呼び出して、第 1 パラメータとして D3DRS_LIGHTING を渡し、第 2 パラメータとして TRUE または FALSE を渡す。ステートを TRUE に設定するとライティングが有効になり (デフォルト)、FALSE を設定すると無効になる。


ライトのカラー タイプとソース

Microsoft® Direct3D® の光源は、互いに独立してライティング計算の係数として働く個々のライティング コンポーネントとして、ディフューズ色、アンビエント色、およびスペキュラ色を発する。同様に、システムがレンダリングする頂点は、その頂点フォーマットによって定義された個別のディフューズ色、アンビエント色、スペキュラ色、およびエミッション色を使用する。

Microsoft® Visual Basic® の場合、頂点カラーは、D3DRS_COLORVERTEX レンダリング ステートを TRUE に設定したときにのみ、システムによって使用される。頂点カラー ソースは選択可能である。つまり、実行時にライティング式の頂点カラー部分のソースを選択するように設定できる。D3DRS_AMBIENTMATERIALSOURCE、D3DRS_DIFFUSEMATERIALSOURCE、および D3DRS_SPECULARMATERIALSOURCE レンダリング ステートは、ライティング計算の際にシステムが描画する色のカラー ソースを制御する。各レンダリング ステートは、CONST_D3DMATERIALCOLORSOURCE 列挙のメンバに設定できる。これは、カラー ソースとして現在のマテリアルを使用するか、または頂点の色を使用するかを指定する値を定義する。


フォグ エフェクト

Microsoft® Direct3D® のトランスフォーム & ライティング エンジンでは、ライティング中にフォグ エフェクトを作成できる。このようなフォグは、フォグ情報が、ラスタ化される頂点のアルファ成分に配置されることから、通常は頂点フォグと呼ばれる。

詳細については、「フォグ」および「頂点フォグ」を参照すること。


Direct3D のライティングにおける数学的計算

ここでは、Microsoft® Direct3D® ライティング エンジンのしくみおよび実装の詳細を説明する。Direct3D は、自然光の振る舞いを評価してライティングをモデル化する。Direct3D ライティング モデルは、ライトの色、ライトの進行方向と距離、ビューアの位置座標、およびマテリアルの特性を監視して、面の各頂点で 2 つの色成分を計算する。Direct3D は、これらの色成分を使用して、面のピクセルをラスタ化するときに描画する色を計算する。

注 すべての計算はモデル空間で行われる。ワールド行列の逆行列を使用してカメラ位置座標と共にライトの位置座標と方向をモデル空間にトランスフォームし、次に逆トランスフォームする。その結果、ワールド行列またはビュー行列によって一様でないスケーリングが生じる場合は、最終的なライティングが不正確になることがある。

ここでは、ディフューズ成分とスペキュラ成分を提供するために Direct3D で使用する公式について技術的観点から説明する。Direct3D の方法を理解すれば、Direct3D ライティング モデルが要望に合うかどうかをより正確に判断できるようになる。Direct3D ライティング モデルは、正確さ、効率性、および使いやすさを目指して設計されている。しかし、Direct3D で使用する公式がニーズに合わない場合は、Direct3D ライティング モジュールは使用せず、独自のライティング モデルを実装することもできる。説明するトピックは、次のとおりである

  • ライティング表記
  • カメラ空間トランスフォーム
  • 基本的なライティング公式
  • ディフューズ公式
  • スペキュラ公式
  • 距離の増加によるライトの減衰
  • 反射率モデル
  • スポットライト フォールオフ モデル

この公式で使用されるパラメータを、次の表に示す。各表には、対応するデフォルト値、型、および許容値の範囲を示す。

次の表は、位置パラメータを示している。

パラメータ | デフォルト値 | 型 | 説明
Pe | (0,0,0) | D3DVECTOR | カメラ空間でのカメラの位置座標。
Po | N/A | D3DVECTOR | カメラ空間における現在のモデル原点 (0,0,0,1) の位置。これは Mw*Mv 行列の 4 行目である。
Mw | N/A | D3DMATRIX | D3DTRANSFORMSTATE_VIEW によって設定されるワールド行列。
Mv | N/A | D3DMATRIX | D3DTRANSFORMSTATE_VIEW によって設定されるビュー行列。
Mwv | N/A | D3DMATRIX | Mw*Mv。
Halfway | N/A | D3DVECTOR | 正規化されたベクトル。スペキュラ反射を計算するために使用される。
La | (0.0, 0.0, 0.0, 0.0) | D3DCOLORVALUE | ライト ステートのアンビエント色。D3DRENDERSTATE_AMBIENT によって設定される。
V | N/A | D3DVECTOR | カメラ空間での頂点の位置座標。
N | N/A | D3DVECTOR | カメラ空間での正規化された頂点の法線。
Vcd | N/A | D3DCOLORVALUE | 頂点のディフューズ色。
Vcs | N/A | D3DCOLORVALUE | 頂点のスペキュラ色。

次の表は、マテリアル パラメータを示している。

パラメータ | デフォルト値 | 型 | 説明
Ma | (0.0, 0.0, 0.0, 0.0) | D3DCOLORVALUE | アンビエント色。
Md | (255, 255, 255, 255) | D3DCOLORVALUE | ディフューズ色。
Ms | (0.0, 0.0, 0.0, 0.0) | D3DCOLORVALUE | スペキュラ色。
Me | (0.0, 0.0, 0.0, 0.0) | D3DCOLORVALUE | エミッション色。
Mp | 0.0 | D3DVALUE | スペキュラ指数。範囲 : (-∞,+∞)

次の表は、光源 i パラメータを示している。

パラメータ | デフォルト値 | 型 | 説明
LpI | (0.0, 0.0, 0.0) | D3DVECTOR | カメラ空間での位置座標。
LdI | (0.0, 0.0, 1.0) | D3DVECTOR | カメラ空間でのライトへの方向。
LrI | 0.0 | D3DVALUE | 距離の範囲。範囲 : [0.0, D3DLIGHT_RANGE_MAX]。
LcaI | (0.0, 0.0, 0.0, 0.0) | D3DCOLORVALUE | アンビエント色。
LcsI | (0.0, 0.0, 0.0, 0.0) | D3DCOLORVALUE | スペキュラ色。
LcI | (1.0, 1.0, 1.0, 0.0) | D3DCOLORVALUE | ディフューズ色。
att0I | 0.0 | D3DVALUE | 固定減衰係数。範囲 : (0, +∞)
att1I | 0.0 | D3DVALUE | 線形減衰係数。範囲 : (0, +∞)
att2I | 0.0 | D3DVALUE | 2 次減衰係数。範囲 : (0, +∞)
falloffI | 0.0 | D3DVALUE | フォールオフ係数。範囲 : (-∞, +∞)
thetaI | 0.0 | D3DVALUE | スポットライトの本影角度 (ラジアン単位)。範囲 : [0, π)
phiI | 0.0 | D3DVALUE | スポットライトの半影角度 (ラジアン単位)。範囲 : [thetaI, π)。


ライティング表記

ライティング公式では次の表記を使用する。

D3DCOLORVALUE コンポーネントの範囲は (-∞, +∞) である。

・ - 内積は d1 ・ d2 = max{d1・d2, 0} として定義される。

norm(P) - 単位ベクトル、またはベクトルの正規化

V1V2 - ポイント V1 からポイント V2 へのベクトル

M-1- 逆行列

MT- 転置行列

V1 / V2。V1 および V2 は D3DVECTOR 型である。この型はベクトル (V1.x / V2.x, V1.y / V2.y , V1.z / V2.z) と同等である。

V1 * V2。V1 および V2 は D3DVECTOR 型である。この型はベクトル (V1.x * V2.x, V1.y * V2.y , V1.z * V2.z) と同等である。


カメラ空間トランスフォーム

カメラ空間の頂点は、オブジェクトの頂点に Mwv 行列を乗算することによって計算される。

v = Vobject * Mwv

カメラ空間の法線は、オブジェクトの法線に逆転置行列 Mwv を乗算し、その結果を正規化することによって計算される。

N = Nobject * (Mwv-1)T

D3DRENDERSTATE_NORMALIZENORMALS が TRUE に設定されている場合、法線はカメラ空間へのトランスフォームの後、正規化される。

N = norm(N)

カメラ空間でのライトの位置座標 (Lpi) は、光源の位置座標に Mv を乗算することによって計算される。

Lpi = Lporiginal * Mv

D3DLIGHT_DIRECTIONAL ライトのカメラ空間でのライトへの方向は、光源の位置座標に Mv 行列を乗算し、その結果を正規化して否定することによって計算される。

Ldi = -norm(Ldi original * Mv)

D3DLIGHT_POINT および D3DLIGHT_SPOT の場合は、ライトへの方向は次のように計算される。

Ldi = norm(VLpi)


基本的なライティング公式

ライティング ステージの出力は、RGBA フォーマットでのディフューズ (D) 色およびスペキュラ (s) 色である。ライティングは次の 2 つのステートのいずれかである。

1. ライティング オフ (D3DRENDERSTATE_LIGHTING が FALSE に設定されている)。このステートでは、頂点カラーは次のように計算される。

D3DRENDERSTATE_COLORVETEX は無視される。

ディフューズ頂点カラーが存在する場合、出力ディフューズ色は頂点のディフューズ色に等しい。それ以外の場合は、ディフューズ色はデフォルトのディフューズ色 (255,255,255,255) に等しい。出力ディフューズ色は [0, 255] の範囲にスケーリングおよびクランプされる。

スペキュラ頂点カラーが存在する場合、出力スペキュラ色は頂点のスペキュラ色に等しい。それ以外の場合は、スペキュラ色はデフォルトのスペキュラ色 (0,0,0,0) に等しい。出力スペキュラ色は [0, 255] の範囲にスケーリングおよびクランプされる。

2. ライティング オン (D3DRENDERSTATE_LIGHTING が TRUE に設定されている)。このステートでは、Direct3D は以下の公式に従って頂点カラーを計算する。

頂点に法線が存在しない場合、ライティングの式で内積に依存する部分は 0 に設定される。ライティングが計算される。

ライティングがカメラ空間で行われる。

alpha 成分は次のライティングの式では使用されない。


ディフューズ公式

ここでは、ディフューズ ライティングの公式について説明する。

D3DRENDERSTATE_SPECULARENABLE が FALSE に設定されている場合、スペキュラ成分は (0, 0, 0, 0) に設定される。それ以外の場合は、次のように計算される。

ここで


スペキュラ公式

ここでは、スペキュラ ライティングの公式について説明する。

hi は法線とライトへの方向の間の中間ベクトルである。

hi = norm(norm(Vpe) + Ldi))。D3DRENDERSTATE_LOCALVIEWER = TRUE の場合

hi = norm((0,0,-1) + Ldi))。D3DRENDERSTATE_LOCALVIEWER = FALSE の場合

rhoi = norm(Ldi) • norm(VLpi)

di は頂点からライト i までの距離で、次のように計算される。

すべてのライトが処理され、個別に補間された後、ディフューズ成分およびスペキュラ成分は 0 ～ 255 にクランプされる。


距離の増加によるライトの減衰

Microsoft® Direct3D® では、ライトで照らされた頂点と光源の間の距離を、ライトの位置座標と頂点の間のベクトルのマグニチュードによって決定する。これを次の公式で表す。

この公式では、D は計算する距離、V はライトで照らされた頂点の位置座標、L は光源の位置座標である。D がライトの範囲 (D3DLIGHT8 型の Range メンバ) より大きい場合、Direct3D はそれ以上減衰計算を実行せず、ライティング エフェクトを頂点に適用しなくなる。距離がライティングの範囲内にある場合は、Direct3D は以下の公式を適用して、距離の増加に伴うポイント ライトおよびスポットライトのライトの減衰を計算する。ディレクショナル ライトは減衰しない。

この減衰公式では、A は計算した全減衰、D は光源から頂点までの距離である。attenuation0、attenuation1、および attenuation2 の値は、ライト オブジェクトの D3DLIGHT8 型のメンバによって指定される、ライティングの減衰定数である。対応するメンバはそれぞれ、Attenuation0、Attenuation1、および Attenuation2 である。

減衰定数は公式では係数になる。これらの係数に簡単な調整を加えることで、さまざまな減衰カーブを生成できる。Attenuation0 を 1.0 に設定して、減衰しない光を作成できる (ただし、範囲による制限がある)。また、いろいろな値を試してみて、さまざまな減衰エフェクトを出すことができる。

ライティングの最大範囲における減衰は 0.0 ではない。ライティングの範囲内でライティングが突然現れるのを防止するために、アプリケーションではライティングの範囲を増やすことができる。また、アプリケーションで、ライティング範囲における減衰係数が 0.0 に近づくように減衰定数を設定できる。減衰値をライティングの色の赤、緑、および青成分で乗算して、ライティングの強度を光が頂点まで進む距離の係数として定めることができる。

ライティング減衰を計算した後、Direct3D では、スポットライト エフェクト (適用する場合)、サーフェスからの光の反射角度、および現在のマテリアルの反射率を考慮して、その頂点に対するディフューズ成分とスペキュラ成分を算出する。詳細については、「スポットライト フォールオフ モデル」および「反射率モデル」を参照すること。


反射率モデル

すべての減衰エフェクトでライティング強度を調整した後、Microsoft® Direct3D® では頂点法線と入射光の方向の角度を仮定して、頂点から反射する残光の量を計算する。ディレクショナル ライトではこの手順は実行されない。距離が増加しても光が減衰しないためである。

Direct3D ではディフューズとスペキュラの 2 種類の反射を考慮し、異なる公式を使用して各ライティングで反射する光の量を決定する。反射するライティングの量を計算した後、Direct3D はこれらの新しい値を、現在のマテリアルのディフューズ反射率プロパティとスペキュラ反射率プロパティに適用する。この結果として生じるカラー値は、グーロー シェーディングとスペキュラ ハイライト生成のためにラスタライザが使用するディフューズ成分とスペキュラ成分である。

ディフューズ反射モデル

Microsoft Direct3D では、次の公式を使用してディフューズ反射係数を計算する。

この公式では、Rd はディフューズ反射係数、D はライトが頂点に向かう方向、N は頂点法線である。ベクトル D は正規化される。ベクトル N は、D3DRS_NORMALIZENORMALS レンダリング ステートが有効になっている場合にのみ正規化される。ライティングの方向ベクトルに -1 を乗じて逆ベクトルにして、方向ベクトルと頂点法線の間の適正な関係付けを作成する。この公式の結果は -1.0 ～ 1.0 の範囲の値である。この値は 0.0 ～ 1.0 の範囲に制限され、頂点から反射されるライティングの強度を調整するために使用される。

ディフューズ反射係数を計算した後で、その結果を次のようなディフューズ反射公式に適用して、その頂点におけるディフューズ成分が決定される。次の公式は、アンビエント反射とディフューズ反射を組み合わせて頂点におけるディフューズ成分を作成する。

この公式では、Dv は頂点に対して計算されるディフューズ成分、Ia はシーン内のアンビエント ライト、および A は距離とスポットライト エフェクトのために減衰した光源のライティング強度 (スポットライト フォールオフ モデルで乗算された、距離の増加によるライトの減衰) を表す。変数 L はライティングのプロパティを表し、V エントリは頂点カラーを表す。ここで、それぞれに適用されている添字 a、d、および e は、色の種類のアンビエント (ambient)、ディフューズ (diffuse)、またはエミッション (emissive) を表す。公式で示すように、まず IaVa + Ve が計算され、すべてのアクティブなライティングの A(RdVdLd + VaLa) が加算される。

D3DRS_COLORVERTEX レンダリング ステートが有効になっている場合、D3DRS_AMBIENTMATERIALSOURCE および D3DRS_DIFFUSEMATERIALSOURCE レンダリング ステートに設定された値に基づいて V の色が選択される。これらのレンダリング ステートを CONST_D3DMATERIALCOLORSOURCE 列挙のメンバを設定して、現在のマテリアルか、頂点の色をカラー ソースとして使用する。

詳細については、「スペキュラ反射モデル」を参照すること。

スペキュラ反射モデル

スペキュラ反射をモデル化するには、光の進行方向だけでなく、視点からの視線の方向もシステムに知らせる必要がある。システムでは Phong スペキュラ反射モデルの簡易バージョンを使用する。このモデルでは、中間ベクトルを使用してスペキュラ反射強度を概算する。中間ベクトルは、光源へのベクトルと視点へのベクトルの間の中間に存在する。Microsoft® Direct3D® では、アプリケーションは、D3DRS_LOCALVIEWER レンダリング ステートで制御する 2 種類の方法を使用して、中間ベクトルを計算できる。D3DRS_LOCALVIEWER を TRUE に設定すると、ライトの方向ベクトルに加えて、カメラの位置座標と頂点の位置座標を使用して中間ベクトルが計算される。次の公式はこの計算を示す。

この公式では、norm は入力ベクトルを正規化する演算子、VC は位置座標から視点または目の位置座標へのベクトル、Ld はライティングの方向ベクトルである。

この方法で中間ベクトルを決定する場合は、計算負荷が大きくなることがある。この代わりに、D3DRS_LOCALVIEWER を FALSE に設定することもできる。この場合、z 軸の無限遠方に視点が存在するとして処理される。この設定は計算負荷は少ないが、正確さで劣る。したがって、この方法は、正射影を使用するアプリケーションに最適である。D3DS_LOCALVIEWER を FALSE に設定した場合、Direct3D では次の公式を使用して中間ベクトルを計算する。

この公式は最初の公式に類似しているが、ベクトル VC を計算する代わりに、z 軸上の無限遠方にある視点を表すベクトル I (0, 0, -1) を使用している。

中間ベクトル H を求めた後、システムは次の公式を使用してスペキュラ反射を計算する。

この公式では、Rs はスペキュラ反射率、N は頂点法線、H は中間ベクトル、p は現在のマテリアルのスペキュラ反射強度 (マテリアルの D3DMATERIAL8 型の power メンバで指定) である。ベクトル H は正規化される。ベクトル N は、D3DRS_NORMALIZENORMALS レンダリング ステートが有効になっている場合にのみ正規化される。

ディフューズ反射公式と同様、この公式の結果は -1.0 ～ 1.0 の範囲の値であり、この値は 0.0 ～ 1.0 の範囲に制限され、頂点から反射されるライティングを計算するために使用される。また、ディフューズ反射モデルと同様、その頂点におけるスペキュラ成分を求める公式にその結果が適用される。

この公式では、Sv は計算されるスペキュラ色である。A は、距離およびスポットライト エフェクトのために減衰した単一の光源からのライトである。詳細については、「距離の増加によるライトの減衰」および「スポットライト フォールオフ モデル」を参照すること。変数 Rs は以前に計算されたスペキュラ反射率、Vs は選択された、頂点のスペキュラ成分、Ls はスペキュラ ライトの色である。

D3DRS_COLORVERTEX レンダリング ステートが有効になっている場合、D3DRS_SPECULARMATERIALSOURCE レンダリング ステートの値に基づいて V のカラー ソースが選択される。このレンダリング ステートを CONST_D3DMATERIALCOLORSOURCE 列挙型のメンバに設定して、現在のマテリアルか、頂点の色成分のいずれかをカラー ソースとして使用できる。

詳細については、「ディフューズ反射モデル」を参照すること。


スポットライト フォールオフ モデル

スポットライトは、明るい内部コーンおよび外部コーンの 2 つの部分を持つ光のコーンを放射する。ライティングは、内部コーンの内側が最も明るく、外部コーンの外側にはライティングが存在しない。ライティングの強度は、この 2 つの領域の間で減衰する。一般に、このような減衰をフォールオフと呼ぶ。

頂点を照らす光の量は、頂点が内部コーンの内側にあるか、外部コーンの内側にあるかによって異なる。Microsoft® Direct3D® は、スポットライトの方向ベクトル (L) と頂点からスポットライトへのベクトル (D) の内積を計算する。この値は、2 つのベクトルがなす角度の余弦に等しく、ライティングのコーン角度と比較できる頂点位置座標を示すので、内部コーンまたは外部コーンのどちらに頂点があるかを判断するのに役立つ。次の図は、これら 2 つのベクトルの間の関係を示している。

システムは、この値をスポットライトの内部および外部コーンの角度の余弦と比較する。ライトの D3DLIGHT8 型の Theta および Phi メンバは、内部および外部コーンの角度の合計を表す。減衰は、全コーン角度にわたってではなく、ライティングの中心から頂点が離れることによって生じるため、Direct3D はコーン角度を半分に割ってから余弦を計算する。

ベクトル L と D の内積が外部コーンの角度の余弦以下の場合、頂点は外部コーンの外側に存在し、ライティングで照らされない。L と D の内積が内部コーン角度の余弦より大きい場合、頂点は内部コーンの内側に存在し、最大量のライティングで照らされる (ただし、距離の増加による減衰を考慮する)。頂点が 2 つの領域の間にある場合、Direct3D は次の公式を使用して頂点におけるライティングのフォールオフを計算する。

この公式では、If はライティングされている頂点におけるフォールオフ後の光の強度、a はベクトル L と D がなす角度、f は外部コーンの角度の半分の角度、q は内部コーンの角度の半分の角度、p はスポットライトのフォールオフ プロパティ (D3DLIGHT8 型の Falloff) である。この公式では、頂点における光の強度を定める 0.0 ～ 1.0 の値を求めて、ライトのフォールオフを示す。ライティングから頂点までの距離の係数として減衰も適用される。p 値は、D3DLIGHT8 型の Falloff メンバに対応し、フォールオフ カーブの形状を決定する。次の図は、Falloff 値によってフォールオフ カーブがどのように変化するかを示している。

Falloff 値が変化しても実際のライティングに与える影響はわずかであり、Falloff 値が 1.0 以外のときに形成されるフォールオフ カーブで若干のパフォーマンス低下が生じるのみである。これらの理由により、通常、この値は 1.0 に設定される。

詳細については、「距離の増加によるライトの減衰」を参照すること。


ビューポートとクリッピング

ここでは、ジオメトリ パイプラインの最後の段階のクリッピングについて説明する。説明するトピックは、次のとおりである。

  • ビューポートとは
  • ビューポート矩形
  • クリッピング ボリューム
  • ビューポートのスケーリング
  • ビューポートの使い方

Microsoft® Direct3D® では、ビューポート パラメータのセットを使用することで、デバイスにクリッピングを実装する。


ビューポートとは

概念上、ビューポートとは 3D シーンが射影される 2D 矩形である。Microsoft® Direct3D® の場合、この矩形は、レンダリング ターゲットとして使用される Direct3D サーフェス内の座標として存在する。射影トランスフォームは、ビューポートに使用される座標系に頂点をトランスフォームする。

Direct3D でビューポートを使用して、アプリケーションで次の機能を指定する。

  • レンダリングが限定されるスクリーン空間ビューポート
  • シーンがレンダリングされるレンダリング ターゲット サーフェスの深度値の範囲 (通常は 0.0 ～ 1.0)


ビューポート矩形

Microsoft® Visual Basic® アプリケーションでは、D3DVIEWPORT8 型を使用してビューポート矩形を定義する。D3DVIEWPORT8 型は、Direct3DDevice8 クラスが提供する次のビューポート操作メソッドで使用される。

  • Direct3DDevice8.GetViewport
  • Direct3DDevice8.SetViewport

D3DVIEWPORT8 型には x、y、Width、および Height の 4 つのメンバがある。これらを使用して、シーンがレンダリングされるレンダリング ターゲット サーフェス領域 (ビューポート矩形) を定義する。

これらの値は、次の図に示すように、転送先の矩形、つまりビューポート矩形に対応する。

D3DVIEWPORT8 構造体の x、y、Width、および Height メンバに指定する値は、レンダリング ターゲット サーフェスの左上角からのスクリーン座標である。この型は、シーンがレンダリングされる深度範囲を示す 2 つの追加メンバ MinZ および MaxZ を定義する。

Microsoft® Direct3D® では、ビューポートのクリッピング ボリュームの範囲は、x 方向については -1.0 ～ 1.0、y 方向については 1.0 ～ -1.0 と想定している。この値は、過去のアプリケーションで最もよく使用された設定値である。旧リリースの DirectX と同様、Microsoft DirectX® 8.0 の場合も、射影トランスフォームの際、クリッピングを行う前にビューポートのアスペクト比を調整することができる。このタスクについては、「射影トランスフォーム」で説明する。


クリッピング ボリューム

射影行列の結果によって、射影空間でのクリッピング ボリュームが決まる。Microsoft® Direct3D® は、次のようにして、射影空間のクリッピング ボリュームを定義する。

この式では、Xc、Yc、Zc、および Wc は、射影トランスフォームの適用後の頂点座標を表す。クリッピングが有効な場合 (デフォルト設定)、これらの範囲外に x、y、または z 要素を持つ頂点がクリッピングされる。

頂点バッファを除き、アプリケーションでは、D3DRS_CLIPPING レンダリング ステートを使用してクリッピングを有効または無効にする。頂点バッファのクリッピング情報は処理中に生成される。詳細については、「頂点の処理」を参照すること。

Direct3D は頂点バッファのプリミティブのトランスフォームされた頂点をクリッピングしない。ただし、Direct3DDevice8.ProcessVertices によるものは除く。独自のトランスフォームを実行する際に、Direct3D でクリッピングを行う必要がある場合は、頂点バッファを使用するべきではない。この場合、アプリケーションがデータをトラバースしてトランスフォームし、Direct3D が再度データをトラバースしてクリッピングした後、ドライバがデータをレンダリングするので、効率的ではない。したがって、アプリケーションがデータをトランスフォームする場合は、データのクリッピングも行うべきである。


ビューポートのスケーリング

ビューポート用の D3DVIEWPORT8 型の x、y、Width、および Height メンバに寸法を指定して、レンダリング ターゲット サーフェスのビューポートの位置座標および大きさを定義する。これらの値は、レンダリング ターゲット サーフェスの左上角からのスクリーン座標である。

Microsoft® Direct3D® では、ビューポートの位置座標と寸法を使用して頂点をスケーリングし、レンダリングするシーンをターゲット サーフェス上の適切な位置座標に配置する。内部的には、Direct3D は、各頂点に適用される行列にこれらの値を挿入している。

この行列は、ビューポートの寸法および指定の深度範囲に従って頂点をスケーリングし、その頂点をレンダリング ターゲット サーフェスの適切な位置座標に平行移動する。また、この行列は、y が下方に増加する左上角のスクリーン原点を反映するために y 座標を反転する。この行列を適用した後も、頂点は同次である。つまり、頂点は依然として [x,y,z,w] 頂点として存在するので、ラスタライザに送る前に頂点を非同次にトランスフォームしなければならない。これは、「ラスタ化」で説明するように、単純な除算によって行う。


ビューポートの使い方

ここでは、ビューポートの操作について詳しく説明する。説明するトピックは、次のとおりである。

  • ビューポート クリッピング ボリュームの設定
  • ビューポートのクリア
  • 頂点のマニュアル トランスフォーム


ビューポート クリッピング ボリュームの設定

レンダリング デバイスに対してビューポート パラメータを設定するための条件は、ビューポートのクリッピング ボリュームを設定することだけである。このためには、クリッピング ボリュームとレンダリング ターゲット サーフェス用のクリッピング値を初期化および設定する。ビューポートは、一般には、レンダリング ターゲット サーフェスの全領域にレンダリングするように設定されるが、必ずしもそうする必要はない。

次の Microsoft® Visual Basic® コードでは、この内容を実現するために D3DVIEWPORT8 型の設定を行う。

Dim viewData As D3DVIEWPORT8

With viewData
    .x = 0: .y = 0
    .Width = Width: .Height = Height
    .MinZ = 0#: .MaxZ = 1#
End With

D3DVIEWPORT8 型に値を設定した後、Direct3DDevice8.SetViewport メソッドを呼び出してデバイスにビューポート パラメータを適用する。

' 変数 d3dDevice には、
' Direct3DDevice8 オブジェクトへの有効な参照が格納されているとする。
Call d3dDevice.SetViewport(viewData)

この呼び出しの後、ビューポート パラメータが設定され、次回レンダリング メソッドを呼び出したときにこのビューポート パラメータが有効になる。ビューポート パラメータは、D3DVIEWPORT8 型の値を更新して、再度 SetViewport を呼び出すだけで変更できる。


ビューポートのクリア

ビューポートをクリアすると、レンダリング ターゲット サーフェス上のビューポート矩形の内容と、深度バッファ サーフェスおよびステンシル バッファ サーフェス (指定されている場合) の矩形の内容がリセットされる。通常は、新しいフレームをレンダリングする前にビューポートをクリアして、ゴミを表示せずに、グラフィックスなどのデータが新しいレンダリング オブジェクトを受け入れる準備を整える。

Microsoft® Visual Basic® の Direct3DDevice8 クラスには、ビューポートをクリアする Direct3DDevice8.Clear メソッドがある。このメソッドは、クリアするサーフェス上の領域を定義する 1 つまたは複数の矩形を受け取る。レンダリングするシーンにビューポート矩形全体の移動が含まれている場合 (たとえば、対面型の遠近法を使用するゲーム)、各フレームのビューポート全体をクリアすることができる。この場合、Count パラメータを 1 に設定し、ClearD3DRect パラメータを D3DRECT 変数の単一要素配列に設定する。ここでは、レンダリング ターゲット サーフェスの領域全体に及ぶ矩形を最初の要素でのみ記述する。

Clear メソッドはさまざまな使用方法があり、深度バッファ内のステンシル ビットをクリアすることもできる。Flags パラメータは、レンダリング ターゲットおよび関係する深度バッファまたはステンシル バッファのクリア方法を指定する 3 つのフラグを受け取る。このパラメータに D3DCLEAR_TARGET フラグを指定すると、このメソッドは Color パラメータで指定した任意の RGBA 色 (マテリアル カラーではない) を使用してビューポートをクリアする。D3DCLEAR_ZBUFFER フラグを指定すると、このメソッドは z パラメータで指定した任意の深度に従って深度バッファをクリアする。0.0 は最も近い距離を表し、1.0 は最も遠い距離を表す。D3DCLEAR_STENCIL フラグを指定すると、このメソッドはステンシル ビットを Stencil パラメータで指定した値にリセットする。指定できる値は 0 ～ 2n-1 までの整数である。ここで、n はステンシル バッファのビット深度を示す。

場合によっては、レンダリング ターゲット サーフェスと深度バッファ サーフェスの一部にのみレンダリングすることがある。クリア メソッドは、1 回の呼び出しでサーフェスの複数の領域をクリアすることもできる。これを行うには、Count パラメータにクリアする矩形の数を指定し、ClearD3DRect パラメータに矩形の配列を指定する。


頂点のマニュアル トランスフォーム

Microsoft® Direct3D® アプリケーションでは、3 種類の頂点を使用できる。頂点フォーマットの詳細については、「頂点フォーマット」を参照すること。

未トランスフォーム 未ライティングの頂点
アプリケーションでライティングとトランスフォームを適用しない頂点。ライティング パラメータやトランスフォーム行列を指定しても、これらの値は Direct3D が計算する。
未トランスフォーム ライティング済みの頂点
アプリケーションでライティングは適用するが、トランスフォームは適用しない頂点。
トランスフォーム済み ライティング済みの頂点
アプリケーションでライティングとトランスフォームの両方を適用する頂点。

頂点バッファを使用して、単純な頂点タイプを複雑な頂点タイプに変えることができる。頂点バッファとは、高速なレンダリングを実行するために頂点をまとめて格納してバッチ処理するためのオブジェクトで、プロセッサ固有の機能を利用するように最適化できる。頂点トランスフォームを実行するには、Direct3DDevice8.ProcessVertices メソッドを使用する。ProcessVertices は未トランスフォームの頂点のみ受け取るが、オプションとして頂点へのライティングの適用とクリッピングが可能である。ライティングは ProcessVertices を呼び出したときに適用されるが、クリッピングが実行されるのはレンダリングのときである。

頂点を処理した後、特別なレンダリング メソッドを使用して頂点をレンダリングしたり、頂点バッファ メモリをロックして頂点に直接アクセスすることができる。頂点バッファの使用の詳細については、「頂点バッファ」を参照すること。


ラスタ化

Microsoft® Direct3D® ジオメトリ パイプラインでの処理が終了すると、頂点はレンダリング ターゲット サーフェスのビューポートに適合するようにトランスフォーム、クリッピング、およびスケーリングされ、スクリーン上に描画するためにラスタライザに送る準備がほぼ完了したことになる。しかし、この時点ではまだ頂点は同次であり、ラスタライザは頂点を x、y、z の位置座標と同次 W の逆数 (RHW) という形で受け取ろうとする。Direct3D は x、y、z 座標を w 座標で除算することにより、この同次頂点を非同次頂点に変換する。その後、次の式に示すように、w 座標を反転することで RHW 値を算出する。

算出した値は、表示のためにラスタライザに渡される。ラスタライザは x 座標と y 座標を頂点のスクリーン座標として使用し、z バッファリングが可能な場合は z 座標を深度バッファの深度比較に使用する。RHW 値は、フォグ計算、パースペクティブ補正テクスチャ マッピング、および w バッファリング (深度バッファリングの別の方法) に使用される。


プログラム可能な頂点処理とピクセル処理

Microsoft® DirectX® 8.0 には、高度なプログラム可能性を持つ、新しいグラフィックス パイプラインが用意されている。次の図に、プログラム可能な頂点およびピクセル パイプラインの主なコンポーネントおよびデータ フローを示す。トランスフォームおよびライティング エンジンと DirectX 6.0 および 7.0 のマルチテクスチャリング モジュールは、プログラム可能なパイプラインにおいて頂点およびピクセル シェーダによって置き換えられる。

このパイプラインの最初の新しい部分は、高次プリミティブ モジュールで、ベジェおよび B スプラインなどの高次プリミティブをテッセレートする。頂点シェーダは、頂点データに対してジオメトリ演算を実行するために使用されるプログラム可能モジュールである。頂点シェーダは、標準的なトランスフォームやライティングなど、さまざまな機能を実行できる。ピクセル シェーダは、プログラム可能なピクセル プロセッサである。ピクセル シェーダは、色およびアルファ ブレンディング処理およびテクスチャ アドレッシング処理を制御する。

プログラム可能なシェーダの概要については、「プロシージャ シェーダの概要」を参照すること。

DirectX 8.0 と以前のバージョンの Microsoft Direct3D® パイプラインの比較については、「ジオメトリ パイプラインへの頂点シェーダの組み込み」を参照すること。

パイプラインのプログラム可能ではない (DirectX 6.0 および 7.0 から変更されていない) 部分については、「ビューポートとクリッピング」および「ラスタ化」を参照すること。


プロシージャ シェーダの概要

Microsoft® Direct3D® for Microsoft DirectX® 8.0 では、頂点トランスフォームおよびライティング パイプラインと、ピクセル テクスチャ ブレンディング パイプラインの動作を指定するためにプロシージャ モデルを使用する。プログラム モデル ベースの構文を使ってハードウェアの動作を指定することには、多くの利点がある。

まず、プロシージャ モデルでは、より一般的な構文を使って共通の操作を指定できる。固定機能 API では、プログラム可能とは対照的に、表現する必要がある数多くの処理についてモード、フラグなどを定義しなければならない。さらに、ハードウェアの能力が向上すると (色、テクスチャ、頂点ストリームなどが増加すると)、データ入力数と乗算された操作のトークン空間が複雑になる。一方、プログラム可能なモデルでは、適切な色および適切なテクスチャをライティング モデルの適切な部分に適用するなどの簡単な処理を、直接的な方法で実行できる。使用可能なすべてのモードを検索する必要がなく、マシンのアーキテクチャを理解し、実行する適切なアルゴリズムを指定するだけで済む。

たとえば、次のような既知の機能をサポートできる。

  • 基本的なジオメトリ トランスフォーム
  • 単純なライティング モデル
  • スキニング用の頂点ブレンディング
  • 頂点モーフィング (トゥイーニング)
  • テクスチャ トランスフォーム
  • テクスチャ生成
  • 環境マッピング

次に、プロシージャ モデルは、新しい処理を開発するための簡単なメカニズムを提供する。実行する必要のある処理の多くが、現在の API ではサポートされていないことがある。多くの場合、これはハードウェアの能力の制限によるものではなく、API の制限によるものである。一般的に、これらの処理は、固定機能の API を API の設計者が予想していない方法で無理やり使って、同じ動作を抽出するよりも、単純であり、高速である。

一般的に実装されることが予想される新しい機能には、次のようなものがある。

  • 行列パレットのスキニング。メッシュあたり 8 ～ 10 のボーンを使ったキャラクタ アニメーション。
  • 異方性ライティング。現在、参照テーブルのテクスチャのコストだけで実行できるライティング。
  • Membrane シェーダ。風船、皮膚などのシェーダ (1/cos(視点と法線の内積))。
  • Kubelka-Munk シェーダ。サーフェスを貫通するライトを考慮するシェーダ。
  • プロシージャ ジオメトリ。プロシージャ ジオメトリ (球) を使ってメッシュ合成して、皮膚の下の筋肉をシミュレートする。
  • ディスプレースメント マッピング。並べたり、反復できる波のパターンやこぶを使ってメッシュを変更する。

第 3 に、プロシージャ モデルはスケーラビリティと発展性を提供する。ハードウェアの能力は急速に発展し続けており、プログラムによる表現は非常にスケーラブルなので、同じ API によるプログラムがその発展にあわせて高層化が可能である。次の処理によって、新しい機能および能力を簡単に公開して、追加することができる。

  • 新しい命令を追加する
  • 新しいデータ入力を追加する
  • 固定機能からパイプラインのプログラム可能な部分に新しい機能を追加する

コードは、複雑な処理を表現するための最適なスケーリング プロパティを持つ表現である。さらに、プログラム可能なシェーダに追加された新しい機能について、Direct3D 内部で変更しなければならないコードは非常に少ない。

第 4 に、プロシージャ モデルは親しみやすい。ソフトウェア開発者にとっては、ハードウェアよりもプログラミングの方が理解しやすい。ソフトウェア開発者の要求を満たす API は、ハードウェアの機能をコード パラダイムにマッピングするべきである。

第 5 に、プロシージャ モデルは、フォトリアル レンダリングの遺産を受け継いでいる。ハイエンドのフォトリアル レンダリングでは、長年にわたって、プログラム可能なシェーダが使用されてきた。一般的に、この分野はパフォーマンスの制約を受けないので、プログラム可能なシェーダによって、レンダリング技術の妥協のない、究極の目標が表現される。

最後に、プロシージャ モデルによって、ハードウェアへの直接的なマッピングが可能になる。最新の 3D ハードウェアは、少なくとも頂点処理ステージでは、実際にはかなりプログラム可能である。API によるプログラム可能性によって、アプリケーションが直接このハードウェアにマッピングできるようにする。これにより、要件に応じてハードウェア リソースを管理できる。実行できるレジスタや命令が制限されている場合、そのすべての機能を持つ固定機能の実装を個別に有効にすることは困難である。共有リソースを必要とする多くの機能を一度に有効にすると、予期しない方法で動作を停止する場合がある。プログラム可能な API モデルでは、DirectX の伝統に従い、アプリケーション開発者が直接ハードウェアを操作し、このような制限を意識せずに済むようにして、この問題を回避している。


ジオメトリ パイプラインへの頂点シェーダの組み込み

処理中に、プログラム可能な頂点シェーダは、Microsoft® Direct3D® ジオメトリ パイプラインのトランスフォームおよびライティング モジュールを置き換える。実質的に、トランスフォームおよびライティング処理に関するステート情報は無視される。ただし、頂点シェーダが無効で、固定機能による処理に戻った場合は、現在のステート設定がすべて適用される。

高次プリミティブのテッセレーションはすべて、頂点シェーダの実行前に行う必要がある。シェーダの処理の後にサーフェス テッセレーションを実行する実装環境では、アプリケーションおよびシェーダ コードにわからない方法で実行しなければならない。セマンティクス情報は、通常、シェーダの前には提供されないので、特殊なトークンを使用して、ほかのすべてのコンポーネントが相対的に補間されるベース位置を表す入力ストリーム コンポーネントを識別する。補間できないデータ チャネルはサポートされない。

出力では、頂点シェーダは同次クリップ空間に頂点の位置座標を生成しなければならない。生成できる追加データには、テクスチャ座標、色、フォグ係数などがある。

標準的なグラフィックス パイプラインは、次のタスクを含めて、シェーダごとに頂点出力を処理する。

  • プリミティブ アセンブリ
  • 視錐台およびクリップ面に対するクリッピング
  • 同次除算
  • ビューポートのスケーリング
  • 背面およびビューポートのカリング
  • 三角形のセットアップ
  • ラスタ化

DirectX 8.0 頂点シェーダのクリッピング空間は、DirectX 7.0 および DirectX 8.0 の固定機能による頂点処理と同じである。詳細については、「クリッピング ボリューム」を参照すること。

プログラム可能なジオメトリは、Direct3D アプリケーション プログラミング インターフェイス (API) 内のモードである。有効になっている場合、頂点パイプラインを部分的に置き換える。無効になっている場合、API は DirectX 6.0 および 7.0 での動作と同じ通常の制御を行う。頂点シェーダの実行は、内部の Direct3D ステートを変更せず、Direct3D ステートはシェーダでは使用できない。

FunctionTokenArray パラメータを ByVal 0 にした Direct3DDevice8.CreateVertexShader の呼び出しは、固定機能によるパイプラインのシェーダを作成するために使用される。FunctionTokenArray が ByVal 0 ではない場合は、シェーダはプログラム可能になる。Direct3DDevice8.SetVertexShader の呼び出しは、現在のアクティブ シェーダを設定し、レンダリング パイプラインがプログラムによる頂点処理と固定機能頂点処理のいずれを使用するかを定義する。


頂点プロセッサへの頂点データの提示

次のいずれかのフォーマットを使用して、頂点データを頂点プロセッサに提示できる。

  • 従来の FVF フォーマット
  • プログラム可能なストリーム モデル

注 選択する頂点データ形式は、使用される頂点処理方法 (固定機能とプログラム可能) とは独立しており、いずれの組み合わせも可能である。たとえば、固定機能トランスフォームとライティング パイプラインでストリームを使用し、プログラム可能な頂点シェーダで FVF 頂点を使用できる。


従来の FVF フォーマット

従来の FVF フォーマットを使用するには、次のサンプル コードに示すように、Direct3DDevice8.SetVertexShader メソッドを呼び出すときに、ハンドルではなく FVF を使用する。

Call m_D3DDevice.SetVertexShader(CUSTOM_FVF)

ここでは、従来の FVF フォーマットのタイプについて説明する。

  • Vertex 型レガシ タイプ
    •

  • LVertex 型レガシ タイプ
    •

  • TLVertex 型レガシ タイプ
    •


Vertex 型レガシ タイプ

ここでは、位置、法線、およびテクスチャ座標を持つ頂点を初期化および使用するために必要なステップについて説明する。

最初のステップでは、次のサンプル コードに示すように、カスタム頂点タイプと FVF を定義する。

Private Type Vertex
    x As Single
    y As Single
    z As Single
    nx As Single
    ny As Single
    nz As Single
    tu As Single
    tv As Single
End Type

Const VertexFVF = (D3DFVF_XYZ Or D3DFVF_NORMAL Or D3DFVF_TEX1)

次のステップでは、Direct3DDevice8.CreateVertexBuffer メソッドを呼び出して、4 つの頂点を収めるのに十分な領域を確保した頂点バッファを作成する。これを、次のサンプル コードに示す。

Set BigSquareVB = m_D3DDevice.CreateVertexBuffer( _
                                  4*len(Vertex), VertexFVF, _
                                  D3DUSAGE_WRITEONLY, _
                                  D3DPOOL_DEFAULT)

次のステップでは、各頂点の値を処理する。これを、次のサンプル コードに示す。

Dim v(4) As Vertex
Call BigSquareVB.Lock(0, 0, v(), 0)

v(0).x  = 0.0: v(0).y  = 10.0: v(0).z  = 10.0
v(0).nx = 0.0: v(0).ny = 1.0: v(0).nz = 0.0
v(0).tu = 0.0: v(0).tv = 0.0

v(1).x  = 0.0: v(1).y  = 0.0:  v(1).z  = 10.0
v(1).nx = 0.0: v(1).ny = 1.0:  v(1).nz = 0.0
v(1).tu = 0.0: v(1).tv = 0.0

v(2).x  = 10.0: v(2).y  = 10.0: v(2).z  = 10.0
v(2).nx = 0.0: v(2).ny = 1.0:  v(2).nz = 0.0
v(2).tu = 0.0: v(2).tv = 0.0

v(3).x  = 0.0: v(3).y  = 10.0: v(3).z = 10.0
v(3).nx = 0.0: v(3).ny = 1.0: v(3).nz = 0.0
v(3).tu = 0.0: v(3).tv = 0.0

BigSquareVB.Unlock

頂点バッファは初期化され、レンダリングする準備ができている。次のサンプル コードは、レガシ FVF を使用して正方形を描画する方法を示している。

Call m_D3DDevice.SetVertexShader(VertexFVF)
Call m_D3DDevice.SetStreamSource(0, BigSquareVB, 4*len(Vertex))
Call m_D3DDevice.DrawPrimitive(D3DPT_TRIANGLESTRIP, 0 ,2)

FVF を Direct3DDevice8.SetVertexShader メソッドに渡して、レガシ FVF が使用されること、およびストリーム 0 だけが有効なストリームであることを Direct3D に指示する。


LVertex 型レガシ タイプ

ここでは、位置、ディフューズ色、スペキュラ色、およびテクスチャ座標を持つ頂点を初期化および使用するために必要なステップについて説明する。

最初のステップでは、次のサンプル コードに示すように、カスタム頂点タイプと FVF を定義する。

Private Type LVertex
    x As Single
    y As Single
    z As Single
    diffuse As Long
    specular As Long
    tu As Single
    tv As Single
End Type

Const VertexFVF = (D3DFVF_XYZ Or D3DFVF_DIFFUSE Or _
                   D3DFVF_SPECULAR Or D3DFVF_TEX1)

次のステップでは、Direct3DDevice8.CreateVertexBuffer メソッドを呼び出して、4 つの頂点を収めるのに十分な領域を確保した頂点バッファを作成する。これを、次のサンプル コードに示す。

Set BigSquareVB = m_D3DDevice.CreateVertexBuffer( _
                                  4*len(LVertex), VertexFVF, _
                                  D3DUSAGE_WRITEONLY, _
                                  D3DPOOL_DEFAULT)

次のステップでは、各頂点の値を処理する。これを、次のサンプル コードに示す。

Dim v(4) As LVertex
Call BigSquareVB.Lock(0, 0, v(), 0)

v(0).x  = 0.0: v(0).y  = 10.0: v(0).z  = 10.0
v(0).diffuse = &HFFFF0000;
v(0).specular = &HFF00FF00;
v(0).tu = 0.0: v(0).tv = 0.0

v(1).x  = 0.0: v(1).y  = 0.0:  v(1).z  = 10.0
v(1).diffuse  = &HFF00FF00;
v(1).specular = &HFF00FFFF;
v(1).tu = 0.0: v(1).tv = 0.0

v(2).x  = 10.0: v(2).y  = 10.0: v(2).z  = 10.0
v(2).diffuse  = &HFFFF00FF;
v(2).specular = &HFF000000;
v(2).tu = 0.0: v(2).tv = 0.0

v(3).x  = 0.0: v(3).y  = 10.0: v(3).z = 10.0
v(3).diffuse  = &HFFFFFF00;
v(3).specular = &HFFFF0000;
v(3).tu = 0.0: v(3).tv = 0.0

BigSquareVB.Unlock

頂点バッファは初期化され、レンダリングする準備ができている。次のサンプル コードは、レガシ FVF を使用して正方形を描画する方法を示している。

Call m_D3DDevice.SetVertexShader(VertexFVF)
Call m_D3DDevice.SetStreamSource(0, BigSquareVB, 4*len(LVertex))
Call m_D3DDevice.DrawPrimitive(D3DPT_TRIANGLESTRIP, 0 ,2)

FVF を Direct3DDevice8.SetVertexShader メソッドに渡して、レガシ FVF が使用されること、およびストリーム 0 だけが有効なストリームであることを Direct3D に指示する。


TLVertex 型レガシ タイプ

ここでは、トランスフォーム済み位置、ディフューズ色、スペキュラ色、およびテクスチャ座標を持つ頂点を初期化および使用するために必要なステップについて説明する。

最初のステップでは、次のサンプル コードに示すように、カスタム頂点タイプと FVF を定義する。

Private Type TLVertex
    x As Single
    y As Single
    z As Single
    rhw As Single
    diffuse As Long
    specular As Long
    tu As Single
    tv As Single
End Type

Const VertexFVF = (D3DFVF_XYZRHW Or D3DFVF_DIFFUSE Or _
                   D3DFVF_SPECULAR Or D3DFVF_TEX1)

次のステップでは、Direct3DDevice8.CreateVertexBuffer メソッドを呼び出して、4 つの頂点を収めるのに十分な領域を確保した頂点バッファを作成する。これを、次のサンプル コードに示す。

Set BigSquareVB = m_D3DDevice.CreateVertexBuffer( _
                                  4*len(TLVertex), VertexFVF, _
                                  D3DUSAGE_WRITEONLY, D3DPOOL_DEFAULT)

次のステップでは、各頂点の値を処理する。これを、次のサンプル コードに示す。

Dim v(4) As TLVertex
Call BigSquareVB.Lock(0, 0, v(), 0)

v(0).x  = 0.0: v(0).y  = 10.0: v(0).z  = 10.0: v(0).rhw = 1.0
v(0).diffuse = &HFFFF0000;
v(0).specular = &HFF00FF00;
v(0).tu = 0.0: v(0).tv = 0.0

v(1).x  = 0.0: v(1).y  = 0.0:  v(1).z  = 10.0: v(1).rhw = 1.0
v(1).diffuse  = &HFF00FF00;
v(1).specular = &HFF00FFFF;
v(1).tu = 0.0: v(1).tv = 0.0

v(2).x  = 10.0: v(2).y  = 10.0: v(2).z  = 10.0: v(2).rhw = 1.0
v(2).diffuse  = &HFFFF00FF;
v(2).specular = &HFF000000;
v(2).tu = 0.0: v(2).tv = 0.0

v(3).x  = 0.0: v(3).y  = 10.0: v(3).z = 10.0: v(3).rhw = 1.0
v(3).diffuse  = &HFFFFFF00;
v(3).specular = &HFFFF0000;
v(3).tu = 0.0: v(3).tv = 0.0

BigSquareVB.Unlock

頂点バッファは初期化され、レンダリングする準備ができている。次のサンプル コードは、レガシ FVF を使用して正方形を描画する方法を示している。

Call m_D3DDevice.SetVertexShader(VertexFVF)
Call m_D3DDevice.SetStreamSource(0, BigSquareVB, 4*len(TLVertex))
Call m_D3DDevice.DrawPrimitive(D3DPT_TRIANGLESTRIP, 0 ,2)

FVF を Direct3DDevice8.SetVertexShader メソッドに渡して、レガシ FVF が使用されること、およびストリーム 0 だけが有効なストリームであることを Direct3D に指示する。


プログラム可能なストリーム モデル

ここでは、プログラム可能なストリーム モデルで使用できるシェーダについて説明する。

  • カラー頂点シェーダ
  • シングルテクスチャ シェーダ
  • マルチテクスチャ シェーダ


カラー頂点シェーダ

ここでは、位置とディフィーズ色を持つ単純な頂点シェーダを初期化および使用するために必要なステップについて説明する。

最初のステップでは、位置と色を格納する構造体を宣言する。これを、次のサンプル コードに示す。

Private Type XYZBuff
    x As Single
    y As Single
    z As Single
End Type

Private Type ColBuf
    color As Long
End Type

Const XYZBUFF_FVF = (D3DFVF_XYZ)
Const COLBUFF_FVF = (D3DFVF_DIFFUSE)

次のステップでは、頂点シェーダ宣言を作成する。これを、次のサンプル コードに示す。

Dim decl(5) As Long

decl(0) = D3DVSD_STREAM(0)
decl(1) = D3DVSD_REG(D3DVSDE_POSITION, D3DVSDT_FLOAT3)
decl(2) = D3DVSD_STREAM(1)
decl(3) = D3DVSD_REG( D3DVSDE_DIFFUSE, D3DVSDT_UBYTE)
decl(4) = D3DVSD_END()

次のステップでは、Direct3DDevice8.CreateVertexShader メソッドを呼び出して頂点シェーダを作成する。

Call m_D3DDevice.CreateVertexShader( decl, ByVal 0, vShader, 0)

CreateVertexShader の第 2 パラメータに ByVal を渡して、この頂点シェーダで固定機能パイプラインを使用することを Direct3D に指示する。

頂点バッファと頂点シェーダは、作成後はいつでも使用できる。次のサンプル コードは、頂点シェーダの設定方法、ストリーム ソースの設定方法、および新しい頂点シェーダを使用する三角形リストの描画方法を示している。

Call m_D3DDevice.SetVertexShader( vShader )
Call m_D3DDevice.SetStreamSource( 0, xyzbuf, 4 * len(xyzbuf))
Call m_D3DDevice.SetStreamSource( 1, colbuf, 2 * len(colbuf))
Call m_D3DDevice.SetIndices( IB, 0 )
Call m_D3DDevice.DrawIndexedPrimitive( D3DPT_TRIANGLELIST, 0, max - min + 1, 0, count / 3 )


シングルテクスチャ シェーダ

ここでは、位置とテクスチャ座標を持つ単純な頂点シェーダを初期化および使用するために必要なステップについて説明する。

最初のステップでは、位置と色を格納する構造体を宣言する。これを、次のサンプル コードに示す。

Private Type XYZBuff
    x As Single
    y As Single
    z As Single
End Type

Private Type Tex0Buf
    tu As Single
    tv As Single
End Type

Const XYZBUFF_FVF = (D3DFVF_XYZ)
Const TEX0BUFF_FVF = (D3DFVF_TEX1)

次のステップでは、頂点シェーダ宣言を作成する。これを、次のサンプル コードに示す。

Dim decl(5) As Long

decl(0) = D3DVSD_STREAM(0)
decl(1) = D3DVSD_REG(D3DVSDE_POSITION, D3DVSDT_FLOAT3)
decl(2) = D3DVSD_STREAM(1)
decl(3) = D3DVSD_REG(D3DVSDE_TEXCOORD0, D3DVSDT_FLOAT2)
decl(4) = D3DVSD_END()

次のステップでは、Direct3DDevice8.CreateVertexShader メソッドを呼び出して頂点シェーダを作成する。

Call m_D3DDevice.CreateVertexShader( decl, ByVal 0, vShader, 0)

CreateVertexShader の第 2 パラメータに ByVal を渡して、この頂点シェーダで固定機能パイプラインを使用することを Direct3D に指示する。

頂点バッファと頂点シェーダは、作成後はいつでも使用できる。次のサンプル コードは、頂点シェーダの設定方法、ストリーム ソースの設定方法、および新しい頂点シェーダを使用する三角形リストの描画方法を示している。

Call m_D3DDevice.SetVertexShader( vShader )
Call m_D3DDevice.SetStreamSource( 0, xyzbuf, 4 * len(xyzbuf))
Call m_D3DDevice.SetStreamSource( 1, tex0buf, 2 * len(colbuf))
Call m_D3DDevice.SetIndices( IB, 0 )
Call m_D3DDevice.DrawIndexedPrimitive( D3DPT_TRIANGLELIST, 0, max - min + 1, 0, count / 3 )


マルチテクスチャ シェーダ

ここでは、位置と複数のテクスチャ座標を持つ単純な頂点シェーダを初期化および使用するために必要なステップについて説明する。

最初のステップでは、位置と色を格納する構造体を宣言する。これを、次のサンプル コードに示す。

Private Type XYZBUFF
    x As Single
    y As Single
    z As Single
End Type

Private Type TEX0BUFF
    tu As Single
    tv As Single
End Type

Private Type TEX1BUFF
    tu2 As Single
    tv2 As Single
End Type

Const XYZBUFF_FVF = (D3DFVF_XYZ)
Const TEX0BUFF_FVF = (D3DFVF_TEX1)
Const TEX1BUFF_FVF = (D3DFVF_TEX1)

次のステップでは、頂点シェーダ宣言を作成する。これを、次のサンプル コードに示す。

Dim decl(7) As Long

decl(0) = D3DVSD_STREAM(0)
decl(1) = D3DVSD_REG(D3DVSDE_POSITION, D3DVSDT_FLOAT3)
decl(2) = D3DVSD_STREAM(1)
decl(3) = D3DVSD_REG( D3DVSDE_TEXCOORD0, D3DVSDT_FLOAT2)
decl(4) = D3DVSD_STREAM(2)
decl(5) = D3DVSD_REG( D3DVSDE_TEXCOORD1, D3DVSDT_FLOAT2)
decl(6) = D3DVSD_END()

次のステップでは、Direct3DDevice8.CreateVertexShader メソッドを呼び出して頂点シェーダを作成する。

Call m_D3DDevice.CreateVertexShader( decl, ByVal 0, vShader, 0)

CreateVertexShader の第 2 パラメータに ByVal を渡して、この頂点シェーダで固定機能パイプラインを使用することを Direct3D に指示する。

頂点バッファと頂点シェーダは、作成後はいつでも使用できる。次のサンプル コードは、頂点シェーダの設定方法、ストリーム ソースの設定方法、および新しい頂点シェーダを使用する三角形リストの描画方法を示している。

Call m_D3DDevice.SetVertexShader( vShader )
Call m_D3DDevice.SetStreamSource( 0, xyzbuf, 4 * len(xyzbuf))
Call m_D3DDevice.SetStreamSource( 1, tex0buf, 2 * len(colbuf))
Call m_D3DDevice.SetStreamSource( 2, tex0buf, 2 * len(colbuf))
Call m_D3DDevice.SetIndices( IB, 0 )
Call m_D3DDevice.DrawIndexedPrimitive( D3DPT_TRIANGLELIST, 0, max - min + 1, 0, count / 3 )


DirectX Graphics の使い方

ここでは、アプリケーション開発における Microsoft® Direct3D® および Direct3DX のAPI の使用方法について説明する。

説明するトピックは、次のとおりである。

  • Direct3D オブジェクト
  • Direct3D デバイス
  • Direct3D リソース
  • サーフェス
  • ライト
  • マテリアル
  • 頂点フォーマット
  • テクスチャ
  • 深度バッファ
  • ステンシル バッファ
  • 頂点バッファ
  • インデックス バッファ
  • テクノロジと特殊効果

概要については、「DirectX Graphics の基礎知識」を参照すること。

データ フローの一般的メカニズムや構成の詳細については、「DirectX Graphics について」を参照すること。

プログラム可能なシェーダなど高度な機能については、「DirectX Graphics の高度なトピック｣を参照すること。


Direct3D オブジェクト

ここでは、Microsoft® Direct3D® オブジェクトについて説明する。

  • Direct3D オブジェクトとは
  • Direct3D へのアクセス


Direct3D オブジェクトとは

Microsoft® Direct3D® は、COM オブジェクトとインターフェイスによって実装される。C++ で記述されたアプリケーションからはこれらのインターフェイスとオブジェクトに直接アクセスできるが、Microsoft Visual Basic® アプリケーションの場合は、Visual Basic アプリケーションから DirectX ランタイムにデータを配置する、Microsoft DirectX® for Visual Basic クラスとして現れるコード レイヤとの相互処理を行う。

Direct3D オブジェクトは、アプリケーションで最初に作成され、最後に解放されるオブジェクトである。Direct3D デバイスの能力を列挙および取得する関数には、Direct3D オブジェクトを介してアクセスできる。したがって、アプリケーションはデバイスを作成しないでもデバイスの選択が可能である。


Direct3D へのアクセス

Microsoft Visual Basic® で記述された Microsoft® Direct3D® アプリケーションでは、起動時に、Direct3D 機能を利用するために Direct3D8 クラスへの参照を取得しなければならない。

次のコードは、DirectX8.Direct3DCreate メソッドによる Direct3D クラスへの参照の取得方法を示している。

Dim g_DX As New DirectX8
Dim g_D3D As Direct3D8

    Set g_D3D = g_DX.Direct3DCreate()

    If g_D3D Is Nothing Then Exit Function

Direct3DDevice オブジェクトから、デバイスを作成した Direct3D オブジェクトに移動するには、Direct3DDevice8.GetDirect3D メソッドを使用する。


Direct3D デバイス

ここでは、Microsoft® Direct3D® デバイスの概要について説明する。説明するトピックは、次のとおりである。

  • Direct3D デバイスとは
  • デバイスの種類
  • デバイスでサポートされるプリミティブの種類
  • デバイスの使い方
  • デバイス ステート
  • 消失したデバイス


Direct3D デバイスとは

Microsoft® Direct3D® デバイスとは、Direct3D のレンダリング コンポーネントである。これはレンダリング ステートをカプセル化して保存する。さらに、Direct3D デバイスは、トランスフォーム & ライティング処理を実行し、サーフェスに画像をラスタライズする。次の図に示すように、Direct3D デバイスのアーキテクチャは、トランスフォーム、ライティング、およびラスタ化モジュールから構成される。

Direct3D デバイスのトランスフォーム & ライティング モジュールを使用せずに、アプリケーション独自のトランスフォーム & ライティング モデルを使用することもできる。詳細については、「頂点シェーダ」を参照すること。


デバイスの種類

ここでは、Microsoft® Direct3D® デバイス、およびデバイスの各タイプについて説明する。説明するトピックは、次のとおりである。

  • デバイスの種類について
  • HAL デバイス
  • リファレンス デバイス
  • プラグ可能なソフトウェア デバイス
  • デバイスの動作


デバイスの種類について

Microsoft® Direct3D® が現在サポートしている Direct3D の主要デバイスは、主に 3 種類に分けられる。ハードウェア アクセラレーションによるラスタ化とシェーディング、ハードウェアとソフトウェア両方による頂点処理を行う、ハードウェア アブストラクション レイヤ (HAL) デバイス、リファレンス デバイス、そしてソフトウェアによるラスタ化を提供するプラグ可能なソフトウェア デバイスの 3 種類である。

これら 3 つのデバイスは、3 つの別個のドライバと見なすことができる。ソフトウェア デバイスとリファレンス デバイスは、ソフトウェア ドライバで表され、HAL デバイスは、ハードウェア ドライバで表される。これらのデバイスを有効活用する最も一般的な方法は、HAL デバイスを出荷用アプリケーションに使用し、リファレンス デバイスを機能テストに使用することである。このようなリファレンス ドライバは、サード パーティによって提供され、特定のデバイス (たとえば、まだリリースされていない開発中のハードウェア) をエミュレートする。

アプリケーションが作成する Direct3D デバイスは、アプリケーションが動作するハードウェアの機能に対応していなければならない。Direct3D では、コンピュータにインストールされている 3D ハードウェアにアクセスするか、ソフトウェアで 3D ハードウェア機能をエミュレートするかのいずれかの方法で、レンダリング機能を利用する。したがって、Direct3D は、ハードウェア アクセス用およびソフトウェア エミュレーション用の両方のデバイスを備えている。

ハードウェア アクセラレーション デバイスは、ソフトウェア エミュレーション デバイスよりもさらに高いパフォーマンスを実現する。HAL デバイスは、Direct3D をサポートするすべてのグラフィック アダプタで使用できる。ほとんどの場合、アプリケーションが対象とするのは、何らかのハードウェア アクセラレーションを備え、ソフトウェア エミュレーションによってローエンド コンピュータの機能を使用できるコンピュータである。

リファレンス デバイスを除き、ソフトウェア デバイスは、常にハードウェア デバイスと同じ機能をサポートしているわけではない。アプリケーションは、デバイス機能を調べて、サポートされている機能を確認する必要がある。

Microsoft DirectX® 8.0 によって提供されるソフトウェア デバイスおよびリファレンス デバイスの動作は HAL デバイスの動作と同じであり、HAL デバイス用に作成されたアプリケーション コードは、修正なしでそのまま使用できる。提供されるソフトウェア デバイスおよびリファレンス デバイスの動作は HAL デバイスの動作と同じであるが、デバイスの能力は異なる。また、特定のソフトウェア デバイスでは、わずかな機能セットしか実装できないこともあるので注意すること。


HAL デバイス

プライマリ デバイスはハードウェア アブストラクション レイヤ (HAL) デバイスであり、このデバイスは、ハードウェア アクセラレーションによるラスタ化と、ソフトウェアおよびハードウェアの両方による頂点処理をサポートする。アプリケーションが動作するコンピュータに、Microsoft® Direct3D® をサポートするディスプレイ アダプタが装着されている場合、アプリケーションではそのアダプタを 3D 処理に使用する必要がある。Direct3D の HAL デバイスは、ハードウェアのトランスフォーム、ライティング、およびラスタ化モジュールをすべてまたはその一部を実装する。

アプリケーションは、3D カードに直接アクセスするわけではない。アプリケーションは、Direct3D 関数およびメソッドを呼び出す。Direct3D は、HAL を介してハードウェアにアクセスする。アプリケーションが動作するコンピュータが HAL に対応している場合は、HAL デバイスを使用することで最高のパフォーマンスを実現できる。

Microsoft Visual Basic® で HAL デバイスを作成するには、Direct3D8.CreateDevice メソッドを呼び出し、デバイス タイプとして定数 D3DDEVTYPE_HAL を渡す。詳細については、「デバイスの作成」を参照すること。

注 : ハードウェア デバイスは 8 ビットのレンダリング ターゲット サーフェスにはレンダリングできない。


リファレンス デバイス

Microsoft® Direct3D® は、リファレンス デバイスまたはリファレンス ラスタライザと呼ばれる追加デバイスをサポートしている。ソフトウェア デバイスとは異なり、リファレンス ラスタライザはあらゆる Direct3D 機能をサポートしている。これらの機能は処理速度よりも精度を重視してソフトウェアに実装されているため、結果が得られるまでには時間がかかる。リファレンス ラスタライザは、利用可能な場合は特別な CPU 命令を十分に利用するが、市販アプリケーションは対象としていない。リファレンス ラスタライザは、機能テストやデモンストレーションにのみ使用する。

Microsoft Visual Basic® でリファレンス デバイスを作成するには、Direct3D8.CreateDevice メソッドを呼び出し、デバイス タイプとして定数 D3DDEVTYPE_HAL を渡す。詳細については、「デバイスの作成」を参照すること。


プラグ可能なソフトウェア デバイス

ユーザーのコンピュータが 3D 操作用の特別なハードウェア アクセラレーションを備えていない場合、アプリケーションはソフトウェアで 3D ハードウェアをエミュレートできる。ソフトウェア ラスタ化デバイスは、ソフトウェアで カラー 3D ハードウェアの機能をエミュレートする。ソフトウェア デバイスはソフトウェア エミュレーションなので、ハードウェア アブストラクション レイヤ (HAL) デバイスよりも実行速度が遅い。ただし、ソフトウェア デバイスは、ユーザーの CPU でサポートされている特別な命令を利用してパフォーマンスを向上させる。サポートされる命令セットには、いくつかの AMD プロセッサの AMD 3D-Now! 命令セットや、多くの Intel プロセッサでサポートされる MMX 命令セットなどがある。Microsoft® Direct3D では、3D-Now! 命令セットを使用してトランスフォーム & ライティング処理を高速化し、MMX 命令セットを使用してラスタ化を高速化する。

Direct3D® のソフトウェア ラスタ化は、プラグ可能なソフトウェア デバイスによって提供される。このデバイスは、Direct3D インターフェイスを介して各種ソフトウェア ラスタライザへのアクセスを可能にする。ソフトウェア デバイスは、アプリケーションによってロードされて、Direct3D オブジェクトに登録される。この時点で、ソフトウェア デバイスを使ってレンダリングを実行する Direct3DDevice オブジェクトを作成できる。

Direct3D ソフトウェア デバイスは、ハードウェア デバイス ドライバ インタフェース (DDI) に類似するインターフェイスを介して Direct3D と通信する。

Direct3D DDK には、プラグ可能なソフトウェア デバイスを開発するためのドキュメントとヘッダーが用意されている。


デバイスの動作

Microsoft® Direct3D® では、デバイスの動作と種類を指定できる。Direct3D8.CreateDevice メソッドでは、1 つまたは複数の動作フラグを組み合わせて Direct3D デバイスのグローバルな動作を制御できる。これらの動作によって Direct3D のランタイム部分で保持されるものと保持されないものが指定され、デバイスの種類によって使用するドライバが指定される。デバイス動作の組み合わせの中には有効でないものもあるが、すべてのデバイスの種類ですべてのデバイスの動作を使用できる。たとえば、CONST_D3DCREATEFLAGS 列挙の D3DCREATE_PUREDEVICE メンバで作成されたデバイスに CONST_D3DDEVTYPE 列挙の D3DDEVTYPE_SW メンバを指定できる。


デバイスでサポートされるプリミティブの種類

Microsoft® Direct3D® デバイスでは、以下のタイプのプリミティブを作成および操作できる。

  • ポイント リスト
  • 線リスト
  • 線ストリップ
  • 三角形リスト
  • 三角形ストリップ
  • 三角形ファン

Microsoft Visual Basic® アプリケーションのプリミティブは、Direct3DDevice8 クラスのレンダリング メソッドを使用してレンダリングできる。詳細については、「レンダリング」を参照すること。

インデックス付きプリミティブ レンダリング メソッドを使用して、ポイント リストをレンダリングすることはできない。


ポイント リスト

ポイント リストとは、個々のポイントとしてレンダリングされる頂点の集合である。アプリケーションでは、星のフィールドまたはポリゴンのサーフェス上の点線に、3D シーンのポイント リストを使用できる。

次の図は、レンダリングされるポイント リストを示している。

ポイント リストにはマテリアルとテクスチャを適用できる。マテリアルまたはテクスチャの色は、描画されたポイントでのみ表示され、ポイントとポイントの間には表示されない。

次のコードは、ポイント リストに対して頂点を作成する方法を示している。

Private Type CUSTOMVERTEX
    x As Single
    y As Single
    z As Single
End Type

Dim Vertices(5) As CUSTOMVERTEX
With Vertices(0): .x = -5.0: .y = -5.0: .z = 0.0: End With
With Vertices(1): .x =  0.0: .y =  5.0: .z = 0.0: End With
With Vertices(2): .x =  5.0: .y = -5.0: .z = 0.0: End With
With Vertices(3): .x = 10.0: .y =  5.0: .z = 0.0: End With
With Vertices(4): .x = 15.0: .y = -5.0: .z = 0.0: End With
With Vertices(5): .x = 20.0: .y =  5.0: .z = 0.0: End With


線リスト

線リストとは、個々の直線の線分のリストである。線リストは、3D シーンでみぞれや大雨を表現するときなどに便利である。アプリケーションでは、頂点の配列に値を設定することで線リストを作成する。線リストの頂点の数は、2 以上の偶数でなければならない。

次の図は、レンダリングされる線リストを示している。

線リストにはマテリアルとテクスチャを適用できる。マテリアルまたはテクスチャの色は、描画された線に沿ってのみ表示され、線と線の間には表示されない。

次のコードは、線リストに対して頂点を作成する方法を示している。

Private Type CUSTOMVERTEX
    x As Single
    y As Single
    z As Single
End Type

Dim Vertices(5) As CUSTOMVERTEX
With Vertices(0): .x = -5.0: .y = -5.0: .z = 0.0: End With
With Vertices(1): .x =  0.0: .y =  5.0: .z = 0.0: End With
With Vertices(2): .x =  5.0: .y = -5.0: .z = 0.0: End With
With Vertices(3): .x = 10.0: .y =  5.0: .z = 0.0: End With
With Vertices(4): .x = 15.0: .y = -5.0: .z = 0.0: End With
With Vertices(5): .x = 20.0: .y =  5.0: .z = 0.0: End With


線ストリップ

線ストリップとは、線分どうしを結合したものから構成されるプリミティブである。線ストリップを使用して、閉じていないポリゴンを作成できる。閉じたポリゴンとは、最後の頂点が最初の頂点と線分で結合されているポリゴンである。線ストリップに基づいてポリゴンを作成する場合、そのポリゴンの頂点が同一平面上にあるとは限らない。

次の図は、レンダリングされる線ストリップを示している。

次のコードは、線ストリップに対して頂点を作成する方法を示している。

Private Type CUSTOMVERTEX
    x As Single
    y As Single
    z As Single
End Type

Dim Vertices(5) As CUSTOMVERTEX
With Vertices(0): .x = -5.0: .y = -5.0: .z = 0.0: End With
With Vertices(1): .x =  0.0: .y =  5.0: .z = 0.0: End With
With Vertices(2): .x =  5.0: .y = -5.0: .z = 0.0: End With
With Vertices(3): .x = 10.0: .y =  5.0: .z = 0.0: End With
With Vertices(4): .x = 15.0: .y = -5.0: .z = 0.0: End With
With Vertices(5): .x = 20.0: .y =  5.0: .z = 0.0: End With


三角形リスト

三角形リストとは、個々の三角形のリストである。三角形は互いに隣接していても離れていてもよい。三角形リストには、少なくとも 3 つの頂点が必要である。頂点の総数は 3 の倍数でなければならない。

独立した要素から構成されるオブジェクトの作成には、三角形リストを使用する。たとえば、3D ゲームで電磁力界壁を作成するには、単独の小さな三角形を多数集めたリストを指定する。次に、この三角形リストにマテリアルやテクスチャを適用して、光を発しているように見せる。壁の三角形それぞれが輝いて見えるようになる。プレーヤーが電磁力界とはこう見えるだろうと期待するとおりに、壁の背後のシーンが三角形の間の隙間を通して部分的に見えるようになる。

また、三角形リストは、グーロー シェーディングで陰影を付けた、鋭いエッジを持つプリミティブを作成するときに便利である。「面法線ベクトルと頂点法線ベクトル」を参照すること。

次の図は、レンダリングされる三角形リストを示している。

次のコードは、三角形リストに対して頂点を作成する方法を示している。

Private Type CUSTOMVERTEX
    x As Single
    y As Single
    z As Single
End Type

Dim Vertices(5) As CUSTOMVERTEX
With Vertices(0): .x = -5.0: .y = -5.0: .z = 0.0: End With
With Vertices(1): .x =  0.0: .y =  5.0: .z = 0.0: End With
With Vertices(2): .x =  5.0: .y = -5.0: .z = 0.0: End With
With Vertices(3): .x = 10.0: .y =  5.0: .z = 0.0: End With
With Vertices(4): .x = 15.0: .y = -5.0: .z = 0.0: End With
With Vertices(5): .x = 20.0: .y =  5.0: .z = 0.0: End With


三角形ストリップ

三角形ストリップとは、一連の結合された三角形である。三角形は結合されているため、各三角形に対して 3 つの頂点すべてをアプリケーションで繰り返し指定する必要はない。たとえば、次の三角形ストリップを定義する場合、必要となるのは 7 つの頂点だけである。

システムでは、頂点の v1、v2、v3 を使用して最初の三角形を、v2、v4、v3 を使用して 2 番目の三角形を、v3、v4、v5 を使用して 3 番目の三角形を、v4、v6、v5 を使用して 4 番目の三角形を、という手順で描画していく。2 番目と 4 番目の三角形の頂点が順序どおりでないことに注意する。これは、すべての三角形が時計回りの向きに描画されることを保証するために必要である。

3D シーンのほとんどのオブジェクトは三角形ストリップで構成されている。これは、三角形ストリップを使用して複雑なオブジェクトを指定すると、メモリを効率的に利用して処理時間を短縮できるからである。

次の図は、レンダリングされる三角形ストリップを示している。

次のコードは、三角形ストリップに対して頂点を作成する方法を示している。

Private Type CUSTOMVERTEX
    x As Single
    y As Single
    z As Single
End Type

Dim Vertices(5) As CUSTOMVERTEX
With Vertices(0): .x = -5.0: .y = -5.0: .z = 0.0: End With
With Vertices(1): .x =  0.0: .y =  5.0: .z = 0.0: End With
With Vertices(2): .x =  5.0: .y = -5.0: .z = 0.0: End With
With Vertices(3): .x = 10.0: .y =  5.0: .z = 0.0: End With
With Vertices(4): .x = 15.0: .y = -5.0: .z = 0.0: End With
With Vertices(5): .x = 20.0: .y =  5.0: .z = 0.0: End With


三角形ファン

三角形ファンとは、次の図に示すように、すべての三角形が 1 つの頂点を共有するという点を除いては、三角形ストリップに類似したものである。

システムでは、頂点 v2、v3、v1 を使用して最初の三角形を、v3、v4、v1 を使用して 2 番目の三角形を、v4、v5、v1 を使用して 3 番目の三角形を、という手順で描画していく。フラット シェーディングが有効な場合、三角形は最初の頂点の色でシェーディングされる。

次の図は、レンダリングされる三角形ファンを示している。

次のコードは、三角形ファンに対して頂点を作成する方法を示している。

Private Type CUSTOMVERTEX
    x As Single
    y As Single
    z As Single
End Type

Dim Vertices(5) As CUSTOMVERTEX
With Vertices(0): .x =  0.0: .y =  0.0: .z = 0.0: End With
With Vertices(1): .x = -5.0: .y = -5.0: .z = 0.0: End With
With Vertices(2): .x = -3.0: .y =  7.0: .z = 0.0: End With
With Vertices(3): .x =  0.0: .y = 10.0: .z = 0.0: End With
With Vertices(4): .x =  3.0: .y =  7.0: .z = 0.0: End With
With Vertices(5): .x =  5.0: .y =  5.0: .z = 0.0: End With


デバイスの使い方

ここでは、アプリケーションにおける Microsoft® Direct3D® デバイスの使用方法について説明する。説明するトピックは、次のとおりである。

  • ハードウェア サポートの判定
  • デバイスの選択
  • デバイスの作成
  • トランスフォームの設定
  • 頂点データの処理
  • マウス カーソルの操作
  • レンダリング


ハードウェア サポートの判定

Direct3D では、次の機能によってハードウェア サポートを判定する。

Direct3D8.CheckDeviceFormat
サーフェス フォーマットが、テクスチャとして使用できるかどうか、テクスチャとレンダリング ターゲットとして使用できるかどうか、および深度ステンシル バッファとして使用できるかどうかを検証するために使用する。さらに、深度バッファ フォーマット サポートと深度ステンシル バッファ フォーマット サポートを検証する場合にも、このメソッドを使用する。
Direct3D8.CheckDeviceType
デバイスが、ハードウェア アクセラレーションを実行できるかどうか、プレゼンテーションのスワップ チェーンを作成できるかどうか、現在のディスプレイ フォーマットにレンダリングできるかどうかを検証するために使用する。
Direct3D8.CheckDepthStencilMatch
深度ステンシル バッファ フォーマットがレンダリング ターゲット フォーマットと互換性があるかどうかを検証するために使用する。このメソッドを呼び出す前に、アプリケーションから深度ステンシルとレンダリング ターゲットの両方のフォーマットに対して CheckDeviceFormat を呼び出す必要があることに注意すること。


デバイスの選択

アプリケーションは、サポートされている Microsoft® Direct3D® デバイス タイプをハードウェアに照会して検出できる。ここでは、ディスプレイ アダプタの列挙と Direct3D デバイスの選択に関わる基本タスクについて説明する。

アプリケーションは、適切な Direct3D デバイスを選択するための一連のタスクを実行する必要がある。以下のステップは、フルスクリーン アプリケーションのタスクである。多くの場合、ウィンドウ アプリケーションではこれらのステップの大部分を省略できる。

  1. 最初に、アプリケーションはシステム上のディスプレイ アダプタを列挙する必要がある。アダプタは、ハードウェアの物理的部品である。デュアル ヘッド ディスプレイの場合と同様、グラフィックス カードに複数のアダプタが搭載されている場合もあるので注意すること。マルチモニタ サポートに関連しないアプリケーションでは、このステップを無視し、ステップ 2 で Direct3D8.EnumAdapterModes メソッドに D3DADAPTER_DEFAULT を渡す。
  2. アプリケーションは、アダプタごとに EnumAdapterModes を呼び出して、そのアダプタがサポートするディスプレイ モードを列挙する。
  3. 必要に応じて、Direct3D8.CheckDeviceType を呼び出し、列挙された各ディスプレイ モードにハードウェア アクセラレーションが存在するかどうかをチェックする。これは CheckDeviceType で使用できる方法の 1 つにすぎない。詳細については、「ハードウェア サポートの判定」を参照すること。
  4. アプリケーションは Direct3D8.GetDeviceCaps メソッドを呼び出し、このアダプタのデバイスに必要なレベルの能力があるかチェックする。このメソッドによって、必要な能力をサポートしていないデバイスが選択対象から外される。GetDeviceCaps によって返されるデバイス能力は、CheckDeviceType で検証されたすべてのディスプレイ モードにおいて、デバイスごとに一定であることが保証されている。
  5. デバイスは常に、そのデバイスがサポートするフォーマットとして列挙されたディスプレイ モードのフォーマットを持つサーフェスにレンダリングする。異なるフォーマットのサーフェスにレンダリングする場合は、Direct3D8.CheckDeviceFormat を呼び出す。デバイスがそのフォーマットにレンダリングできる場合は、GetDeviceCaps が返すすべての能力が適用可能であることが保証される。
  6. 最後に、Direct3D8.CheckDeviceMultiSampleType メソッドを使って、レンダリング フォーマットでフルシーン アンチエイリアシングなどのマルチサンプリング テクニックがサポートされているかどうかを判定できる。

上記のステップを完了すると、アプリケーションでは、処理できるディスプレイ モードのリストが完成する。最後のステップでは、デバイスがアクセス可能なメモリに、必要な数のバッファとアンチエイリアシングを確保できるスペースがあるかどうかを検証する。このテストを必要とする理由は、モードとマルチサンプルの組み合わせによって消費されるメモリ量が、実際に検証する以外の方法では予測不可能だからである。さらに、ディスプレイ アダプタのアーキテクチャによっては、一定量のデバイス アクセス可能なメモリが用意されていないことがある。つまり、フルスクリーン モードに移行するときにビデオ メモリ障害が発生した場合は、アプリケーションがレポートする必要がある。一般には、アプリケーションがユーザーに提供するモード リストからフルスクリーン モードを削除するか、または使用するバック バッファの数を少なくしたり、メモリ消費の少ないマルチサンプル テクニックを使用して、メモリ消費量の削減を図る。

ウィンドウ アプリケーションでも同様の一連のタスクを実行する。

  1. ウィンドウのクライアント領域に合うデスクトップ矩形を決定する。
  2. アダプタを列挙し、クライアント領域に合うモニタを使用するアダプタを探す。クライアント領域が複数のアダプタによって所有されている場合は、各アダプタを個別に駆動する方法か、1 つのアダプタを駆動して、プレゼンテーション時には Direct3D によってデバイスからデバイスにピクセルを転送する方法かを選択できる。また、ステップ 1 とステップ 2 を無視して、D3DADAPTER_DEFAULT アダプタを使用する方法もある。この方法では、ウィンドウがセカンダリ モニタ上に配置されると処理速度が遅くなる場合がある。
  3. アプリケーションは、デスクトップ モード中に CheckDeviceType を呼び出して、デバイスが指定されたフォーマットのバック バッファへのレンダリングをサポートできるかどうかを判定しなければならない。Direct3D8.GetAdapterDisplayMode を使用して、デスクトップのディスプレイ フォーマットを判定することができる。


デバイスの作成

注 指定の Microsoft® Direct3D® オブジェクトによって作成されたレンダリング デバイスは、すべて同じ物理リソースを共有する。単一の Direct3D オブジェクトから複数のレンダリング デバイスを作成することは可能であるが、これらはすべて同じハードウェアを共有するため、パフォーマンスが大きく低下する。

Microsoft Visual Basic® アプリケーションで Direct3D デバイスを作成するには、「Direct3D へのアクセス｣で説明するように、まず Direct3D オブジェクトを作成する必要がある。

最初に、Direct3D デバイスを作成するための D3DPRESENT_PARAMETERS 型の値を初期化する。次のコードは、VSYNC でのみバック バッファがフロント バッファにフリップされるウィンドウ アプリケーションを指定する。

Dim d3dDevice As Direct3DDevice8

    Dim d3dpp As D3DPRESENT_PARAMETERS

    d3dpp.Windowed = 1
    d3dpp.SwapEffect = D3DSWAPEFFECT_COPY_VSYNC

次に、Direct3D デバイスを作成する。次の Direct3D8.CreateDevice 呼び出しは、デフォルトのアダプタ、ハードウェア アブストラクション レイヤ (HAL) デバイス、およびソフトウェア頂点処理を指定する。

    Set d3dDevice = g_D3D.CreateDevice(D3DADAPTER_DEFAULT, D3DDEVTYPE_HAL, hWnd, _
                                      D3DCREATE_SOFTWARE_VERTEXPROCESSING, d3dpp)
    If d3dDevice Is Nothing Then Exit Function

デバイス作成後は、そのステートを設定する。


トランスフォームの設定

Microsoft® Visual Basic® では、Direct3DDevice8.SetTransform メソッドを呼び出してトランスフォームを適用する。たとえば、ビュー トランスフォームを設定するには、次のようなコードを使用する。

On Local Error Resume Next
Dim view As D3DMATRIX

' ビュー行列にデータを設定する。

Call d3dDevice.SetTransform(D3DTS_VIEW, view)

If Err.Number <> DD_OK Then
    ' エラー処理コード。
End If

SetTransform を呼び出す場合、第 １ パラメータに設定できる値はいくつかあるが、一般には、D3DTS_WORLD、D3DTS_VIEW、および D3DTS_PROJECTION を設定する。これらのトランスフォーム ステートは、CONST_D3DTRANSFORMSTATETYPE 列挙で定義されている。この列挙には D3DTS_TEXTURE1 から D3DTS_TEXTURE7 までのステートも含まれる。これらを使用して、テクスチャ座標にトランスフォームを適用できる。


頂点データの処理

Direct3DDevice8 クラスは、ソフトウェアとハードウェア両方での頂点処理をサポートする。一般に、ソフトウェアとハードウェアの頂点処理に関するデバイス能力は同じではない。ハードウェアの能力は、ディスプレイ アダプタやドライバによって異なるが、ソフトウェアの能力は一定である。

次のフラグは、ハードウェア アブストラクション レイヤ (HAL) デバイスおよびリファレンス デバイスの頂点処理動作を制御する。

  • D3DCREATE_SOFTWARE_VERTEXPROCESSING
  • D3DCREATE_HARDWARE_VERTEXPROCESSING
  • D3DCREATE_MIXED_MODE_VERTEXPROCESSING

Direct3D8.CreateDevice を呼び出すときは、いずれかの頂点処理動作フラグを指定する。ミックス モード フラグでは、デバイスはソフトウェアとハードウェア両方の頂点処理が可能になる。1 つのデバイスに対して、一度に 1 つの頂点処理フラグしか設定できない。ピュア デバイス (D3DCREATE_PUREDEVICE) を作成するときは、D3DCREATE_HARDWARE_VERTEXPROCESSING フラグが必要なので注意すること。

単一デバイス上に 2 つの頂点処理能力が存在しないようにするため、実行時にはハードウェア頂点処理能力のみを照会できる。ソフトウェアの頂点処理機能は固定され、実行時に照会することはできない。

デバイスのハードウェア頂点処理能力を判定するには、D3DCAPS8 構造体の VertexProcessingCaps メンバを調べる。ソフトウェア頂点処理については、以下の能力がサポートされている。

  • D3DVTXPCAPS_DIRECTIONALLIGHTS
  • D3DVTXPCAPS_LOCALVIEWER
  • D3DVTXPCAPS_MATERIALSOURCE7
  • D3DVTXPCAPS_POSITIONALLIGHTS
  • D3DVTXPCAPS_TEXGEN
  • D3DVTXPCAPS_TWEENING

また、次の表は、ソフトウェア頂点処理モードのデバイスに対して、D3DCAPS8 構造体のメンバに設定される値を示している。

メンバ | ソフトウェア頂点処理能力
MaxActiveLights | 制限なし
MaxUserClipPlanes | 6
MaxVertexBlendMatrices | 4
MaxStreams | 16
MaxVertexIndex | 0xFFFFFFFF

ソフトウェア頂点処理では、制限なしのライト数やプログラム可能な頂点シェーダなど、保証済みの頂点処理能力セットが提供される。ソフトウェア頂点処理とハードウェア頂点処理は、HAL デバイス (ハードウェア頂点処理とソフトウェア頂点処理の両方をサポートする唯一のデバイス タイプ) を使っていつでも切り替えることができる。唯一の要件として、ソフトウェア頂点処理に使用する頂点バッファは、システム メモリ内に割り当てられていなければならない。

注 ハードウェア頂点処理のパフォーマンスは、ソフトウェア頂点処理のパフォーマンスに匹敵する。このため、同一デバイス タイプ内で頂点処理のためのハードウェア エミュレーション機能とソフトウェア エミュレーション機能の両方を提供するとよい。これはラスタ化には適用されない。ラスタ化では、ホスト プロセッサによる処理速度はグラフィックス専用ハードウェアより低速である。したがって、ハードウェア エミュレーションとソフトウェア エミュレーションのラスタ化の両方を単一デバイス タイプ内で提供することはない。単一デバイス内のランタイムとハードウェア (ドライバ） に重複する機能は、ソフトウェア頂点処理のみである。したがって、ほかのデバイス能力はすべて、ドライバによって提供される潜在的に異なる機能である。


マウス カーソルの操作

マウス カーソル メソッドにより、アプリケーションは、画像を格納するサーフェスを提供することによってカラー カーソルを指定できる。アプリケーションのフレーム レートが低速の場合、このカーソルはディスプレイ レートの半分以上の間隔でシステムによって更新される。ただし、カーソルの更新頻度は、モニタのリフレッシュ レートより短くなることはない。

マウス カーソルの位置はシステム カーソルに結合されている （現在のディスプレイ モードの空間上の解像度に合わせて適宜スケーリングされる） が、アプリケーションによって明示的に移動することができる。これは、Microsoft® Win32® API サポート システム マウス カーソルの動作に類似している。Microsoft® Direct3D® アプリケーションにおけるマウス カーソルの使用方法については、以下のリファレンス トピックを参照すること。

  • Direct3DDevice8.ShowCursor
  • Direct3DDevice8.SetCursorPosition
  • Direct3DDevice8.SetCursorProperties

ハードウェアの実装、または Direct3DDevice8.Present を呼び出したときにハードウェア アクセラレーションによるブリット処理を実行する Direct3D ランタイムにより、Direct3D ではマウスをサポートしている。


レンダリング

アプリケーションでは、一連の DrawPrimitive のメソッドを使用して 3D シーンをレンダリングする。DrawPrimitive によるレンダリングについては、次のトピックに分けて説明する。

  • サーフェスのクリア
  • シーンの開始とエンディング
  • シーンのプレゼンテーション
  • プリミティブのレンダリング


サーフェスのクリア

シーンのオブジェクトをレンダリングする前に、レンダリング ターゲット サーフェスのビューポートまたはビューポートのサブセットをクリアする。ビューポートをクリアすると、システムはレンダリング ターゲット サーフェスの描画部分、およびアタッチされた深度バッファまたはステンシル バッファを指定のステートに設定する。その結果、再度レンダリングするサーフェスの領域がリセットされ、深度バッファとステンシル バッファを使用している場合は、その対応する領域がリセットされる。レンダリング ターゲット サーフェスをクリアすると、指定した領域をデフォルトの色やテクスチャに設定できる。深度バッファおよびステンシル バッファに対しては、深度およびステンシル値を設定できる。

ビューポートのクリアには、Direct3DDevice8.Clear メソッドを使用する。

このメソッドの使用方法については、「ビューポートのクリア」を参照すること。

最適化に関する注意 レンダリング ターゲット サーフェスの全領域に及ぶシーンをレンダリングするアプリケーションで、パフォーマンスを改善するには、レンダリング ターゲットではなく、アタッチされた深度およびステンシル バッファ サーフェス (ある場合) をクリアする。この場合、深度バッファをクリアすると、Microsoft® Direct3D® は次にレンダリングするフレームにレンダリング ターゲットを再書き込みすることで、レンダリング ターゲットに対する明示的なクリア処理を冗長にする。ただし、レンダリング ターゲット サーフェスの一部にのみレンダリングする場合は、明示的なクリア処理が必要である。


シーンの開始とエンディング

Microsoft® Visual Basic® アプリケーションでは、Direct3DDevice8.BeginScene メソッドを呼び出して、Microsoft Direct3D® にシーンのレンダリングの開始を知らせる。BeginScene を呼び出すと、システムはその内部データ構造およびレンダリング ステートの可用性と有効性をチェックする。内部フラグを設定して、シーンが進行中であることを示す。シーンの開始後は、さまざまなレンダリング メソッドを呼び出してプリミティブをレンダリングしたり、シーンのオブジェクトを構成する頂点を個別にレンダリングすることができる。シーンの処理中でないときにレンダリング メソッドを呼び出そうとすると失敗する。詳細については、「プリミティブのレンダリング」を参照すること。

シーンが完了したら、Direct3DDevice8.EndScene メソッドを呼び出す。EndScene メソッドは、キャッシュされているデータをフラッシュし、レンダリング サーフェスの完全性を検証し、シーンが進行中であることを伝える内部フラグをクリアする。

レンダリング メソッドはすべて、BeginScene メソッドを呼び出してから EndScene メソッドを呼び出すまでの間に実行しなければならない。サーフェスが消失するか、または内部エラーが発生すると、シーンのメソッドは失敗し、Err.Number にエラー コードが設定される。BeginScene メソッドが失敗した場合、シーンは開始されず、それに続く EndScene の呼び出しも失敗する。レンダリング中にサーフェスが失われた場合、EndScene は失敗する。

これらのケースを以下にまとめる。

  • BeginScene が何らかのエラーを返した場合、シーンは正常に開始されていないため、EndScene を呼び出してはならない。
  • BeginScene は成功したがシーンのレンダリング中にエラーが発生した場合、EndScene を呼び出す必要がある。
  • 何らかの理由で EndScene が失敗した場合は、これを再度呼び出す必要はない。

たとえば、次に示すのは、単純なシーンを処理するコードである。

On Local Error Resume Next

Call d3dDevice.BeginScene
If Err.Number = DD_OK Then
    ' シーンの開始に成功した場合のみ、
    ' プリミティブをレンダリングする。

    ' シーンを閉じる。
    Call d3dDevice.EndScene
    If Err.Number <> DD_OK Then
        ' エラー処理コード。
    End If
End If

シーンを埋め込むことはできない。つまり、次のシーンをレンダリングするには、現在レンダリング中のシーンを完了する必要がある。BeginScene が呼び出されていないのに EndScene を呼び出した場合、エラーが返される。同様に、前のシーンが EndScene メソッドでまだ完了していないときに BeginScene を呼び出すと、エラーが発生する。

シーンのレンダリング中 (BeginScene を呼び出してから EndScene を呼び出すまでの間)、レンダリング ターゲットやテクスチャなどの Direct3D サーフェスに対して GDI 関数を呼び出してはならない。この関数を呼び出そうとすると、GDI 操作の結果が表示されなくなる可能性がある。アプリケーションで GDI 関数を使用する場合は、シーン関数の外ですべての GDI の呼び出しを行うようにする。


シーンのプレゼンテーション

ここでは、プレゼンテーション API (アプリケーション プログラミング インターフェイス) と、ディスプレイへのシーンのプレゼンテーションに関する問題について説明する。

説明するトピックは、次のとおりである。

  • シーンのプレゼンテーションの概要
  • ウィンドウ モードのマルチビュー
  • マルチモニタ処理
  • 深度バッファの操作
  • カラー フロント バッファへのアクセス


シーンのプレゼンテーションの概要

プレゼンテーション API (アプリケーション プログラミング インターフェイス) は、モニタ表示に影響するデバイス ステートを制御するメソッド セットである。このようなメソッドとして、表示設定モードや、画像表示のためのフレーム単位のメソッドなどがある。

  • Direct3DDevice8.Present
  • Direct3DDevice8.Reset
  • Direct3DDevice8.GetGammaRamp
  • Direct3DDevice8.SetGammaRamp
  • Direct3DDevice8.GetRasterStatus

プレゼンテーション API を理解するには、次の用語を知る必要がある。

  • フロント バッファ。グラフィックス アダプタによって変換され、モニタまたはほかの出力デバイスに表示されるメモリの矩形。
  • バック バッファ。サーフェスの内容がフロント バッファに送られる。
  • スワップ チェーン。バック バッファの集合体であり、順番にフロント バッファに提示される。一般的に、フルスクリーン スワップ チェーンはフリップ DDI で連続する画像を提示し、ウィンドウ スワップ チェーンはブリット DDI で画像を提示する。

Microsoft® Direct3D® for Microsoft DirectX® 8.0 は、デバイスのプロパティとして 1 つのスワップ チェーンを持つため、各デバイスには常に少なくとも 1 つのスワップ チェーンがある。Direct3DDevice8 クラスには、非明示的なスワップ チェーンを操作するメソッド セットがある。このメソッド セットは、スワップ チェーン独自のインターフェイスのコピーである。アプリケーションでは追加スワップ チェーンを作成できるが、一般の単一ウィンドウやフルスクリーンのアプリケーションでは必要ない。

Direct3D API for DirectX 8.0 では、フロント バッファに直接公開することはできない。したがって、アプリケーションは、フロント バッファをロックしたりフロント バッファにレンダリングすることはできない。詳細については、「カラー フロント バッファへのアクセス」を参照すること。

注 DirectX 7.x には、組み合わせて呼び出されるプレゼンテーション API がいくつか存在した。DirectDraw7.SetCooperativeLevel、DirectDraw7.SetDisplayMode、および DirectDraw7.CreateSurface によるシーケンスはその良い例である。また、DirectDrawSurface7.Flip メソッドと DirectDrawSurface7.Blt メソッドの組み合わせによって、レンダリングされたフレームをモニタに転送することを知らせた。DirectX 8.0 では、これらの API グループを、Reset と Present の 2 つのメイン メソッドに分割した。Reset には、SetCooperativeLevel、SetDisplayMode、CreateSurface、そして Flip へのいくつかのパラメータが含まれている。Present には、Flip と、Blt のプレゼンテーションの使用が含まれている。

Direct3D8.CreateDevice への呼び出しは、デバイスの非明示的なリセットを示す。DirectX 8.0 API にはプライマリ サーフェスの概念はなく、プライマリ サーフェスを表すオブジェクトを作成することはできない。プライマリ サーフェスは、デバイスの内部プロパティと見なされる。

ガンマ ランプはスワップ チェーンに関連付けられ、Direct3DDevice8.GetGammaRamp および Direct3DDevice8.SetGammaRamp メソッドで操作する。


ウィンドウ モードのマルチビュー

Direct3DDevice オブジェクトを介して所有し操作できるスワップ チェーンに加えて、Direct3DDevice8.CreateAdditionalSwapChain メソッドを使って、同じデバイスから複数のビューに提示するための追加スワップ チェーンを作成できる。

一般に、アプリケーションはビューごとに 1 つのスワップ チェーンを作成し、そのスワップ チェーンを特定のビューに関連付ける。アプリケーションでは、各スワップ チェーンのバック バッファに画像をレンダリングし、Direct3DDevice8.Present メソッドを使ってそれを 1 つずつ提示する。アダプタごとに一度に 1 つのスワップ チェーンしかフルスクリーンにできないことに注意すること。


マルチモニタ処理

フルスクリーン処理においてデバイスのリセット (Direct3DDevice8.Reset) または作成 (Direct3D8.CreateDevice) に成功すると、そのデバイスを作成した Microsoft® Direct3D® オブジェクトがシステム上のすべてのアダプタを所有しているものとしてマークされる。この状態は排他モードと呼ばれ、Direct3D オブジェクトは排他モードを所有している。排他モードでは、ほかの Direct3D オブジェクトによって作成されたデバイスがフルスクリーン処理を行ったりビデオ メモリを割り当てることはできない。また、ある Direct3D オブジェクトが排他モードであると見なされたとき、フルスクリーンになった以外のほかのデバイスは消失状態になる。詳細については、「消失したデバイス」を参照すること。

排他モードでは、Direct3D オブジェクトに、デバイスが使用するフォーカス ウィンドウが知らされる。その Direct3D オブジェクットが所有する最後のフルスクリーン デバイスがウィンドウ モードにリセットされるか破棄されると、排他モードは解放される。

Direct3D オブジェクトが排他モードを所有するとき、デバイスは 2 つのカテゴリに分類される。最初のカテゴリのデバイスには、以下の特性がある。

  • フルスクリーンのデバイスを作成した同じ Direct3D オブジェクトによって作成されている。
  • フルスクリーンのデバイスと同じフォーカス ウィンドウを持つ。
  • どのフルスクリーン デバイスとも異なるアダプタを表す。

このカテゴリのデバイスにはリセット処理や作成処理に関する制限はなく、消失状態にならない。このカテゴリのデバイスは、フルスクリーン モードにすることもできる。

最初のカテゴリに入らないデバイス (別の Direct3D オブジェクトによって作成され、別のフォーカス ウィンドウで作成され、既にフルスクリーンのデバイスがあるアダプタに作成されたデバイス) は、リセットできず、排他モードがなくなるまで消失状態から解放されない。結果として、マルチモニタ アプリケーションでは複数のデバイスをフルスクリーン モードにすることができるが、それは、これらのデバイスがすべて異なるアダプタのデバイスであり、同じ Direct3D オブジェクトによって作成され、しかも同じフォーカス ウィンドウを共有する場合に限られる。


深度バッファの操作

深度バッファはデバイスに関連付けられている。アプリケーションでは、レンダリング ターゲットを設定するときに深度バッファを移動する必要がある。Direct3DDevice8.GetDepthStencilSurface および Direct3DDevice8.SetRenderTarget メソッドは、深度バッファの操作に使用する。


カラー フロント バッファへのアクセス

フロント バッファへのアクセスは、Direct3DDevice8.GetFrontBuffer メソッドを介して行う。ただし、メソッドは提供されていても、テスト用であることが明示されている。したがって、その機能性は保証されない。


プリミティブのレンダリング

ここでは、DrawPrimitive レンダリング メソッドについて、およびこのメソッドのアプリケーションでの使用方法について説明する。

  • 頂点データ ストリーム
  • ストリーム ソースの設定
  • 頂点バッファおよびインデックス バッファからのレンダリング
  • ユーザー メモリ ポインタからのレンダリング


頂点データ ストリーム

Microsoft® Direct3D® のレンダリング インターフェイスは、1 つ以上のデータ バッファに格納された頂点データからプリミティブをレンダリングするメソッドで構成される。頂点データは、頂点の成分を形成する頂点要素の組み合わせから成る。頂点要素は頂点の最小単位であり、位置座標、法線、色などのエンティティを表す。

頂点の成分とは、単一メモリ バッファ内に連続的に (頂点ごとにインターリーブされて) 格納された 1 つ以上の頂点要素である。完全な頂点は、各成分がそれぞれ個別のメモリ バッファにある 1 つ以上の成分から成る。プリミティブをレンダリングするため、複数の頂点の成分が読み出され、頂点処理で完全な頂点が利用できるように組み立てられる。次の図は、頂点の成分を使用してプリミティブをレンダリングする処理を示している。

プリミティブのレンダリングには、2 つのステップがある。まず、1 つ以上の頂点の成分ストリームを設定し、次に、これらのストリームからレンダリングするための DrawPrimitive メソッドを呼び出す。これらのコンポーネント ストリーム内での頂点要素の識別は、頂点シェーダによって指定される。詳細については、「頂点シェーダ」を参照すること。

DrawPrimitive メソッドは、描画を起動するたびに、ある頂点データ セット内の任意の連続するプリミティブ サブセットがレンダリングされるように、頂点データ ストリームにオフセットを指定する。これにより、同じ頂点バッファからレンダリングされるプリミティブのグループ間で、デバイス レンダリング ステートを変更できる。

インデックス付き描画メソッドと、インデックスなし描画メソッドの両方がサポートされている。詳細については、「頂点バッファおよびインデックス バッファからのレンダリング」を参照すること。

レンダリング インターフェイスのセカンダリ セットでは、頂点およびインデックス データをユーザー メモリ ポインタから直接レンダリングできる。詳細については、「ユーザー メモリ ポインタからのレンダリング」を参照すること。


ストリーム ソースの設定

Direct3DDevice8.SetStreamSource メソッドは、頂点バッファをデバイス データ ストリームにバインドし、頂点データと、プリミティブ処理関数にデータを供給するデータ ストリーム ポートの 1 つとを関連付ける。ストリーム データへの実際の参照は、Direct3DDevice8.DrawPrimitive, などの描画メソッドが呼び出されるまでは発生しない。

ストリームは、成分データのユニフォーム配列として定義され、各成分は、位置座標、法線、色などの単一エンティティを表す 1 つ以上の要素で構成される。Stride パラメータは、成分のサイズをバイト単位で指定する。


頂点バッファおよびインデックス バッファからのレンダリング

Microsoft® Direct3D® は、インデックス付きとインデックスなしの両方の描画メソッドをサポートする。インデックス付きメソッドは、すべての頂点の成分へのインデックス セットを 1 つ使用する。頂点データは、頂点バッファ内の Direct3D API に提示され、インデックス付き描画メソッドのインデックス データは、インデックス バッファ内に提示される。詳細については、以下のリファレンス トピックを参照すること。

  • Direct3DDevice8.DrawPrimitive
  • Direct3DDevice8.DrawIndexedPrimitive

これらのメソッドは、データ入力ストリームのカレント セットからプリミティブを描画する。インデックス バッファへのカレント インデックス配列の設定については、「Direct3DDevice8.SetIndices メソッド」を参照すること。


ユーザー メモリ ポインタからのレンダリング

レンダリング インターフェイスのセカンダリ セットでは、頂点およびインデックス データをユーザー メモリ ポインタから直接レンダリングできる。これらのインターフェイスは、頂点データのみの単一ストリームをサポートする。詳細については、以下のリファレンス トピックを参照すること。

  • Direct3DDevice8.DrawPrimitiveUP
  • Direct3DDevice8.DrawIndexedPrimitiveUP

これらのメソッドは、頂点やインデックス バッファではなく、ユーザー メモリ ポインタによって指定されたデータを使ってレンダリングを行う。


デバイス ステート

Microsoft® Direct3D® デバイスはステート マシンである。つまり、アプリケーションでライティング、レンダリング、およびトランスフォーム モジュールのステートを設定し、レンダリング時にそれらのモジュールを介してデータを渡す。

ここでは、レンダリング ステート、および Direct3D で使用する各レンダリング ステートについて詳しく説明する。また、デバイス ステートのグループを 1 回の呼び出しで処理できるデバイス ステート ブロックについても説明する。説明するトピックは、次のとおりである。

  • レンダリング ステート
  • テクスチャ ステージ ステート
  • ステート ブロック


レンダリング ステート

ここでは、レンダリング ステートの概要と、各レンダリング ステートの詳細について説明する。説明するトピックは、次のとおりである。

  • レンダリング ステートについて
  • アルファ ブレンディング ステート
  • アルファ テスティング ステート
  • アンビエント ライト ステート
  • アンチエイリアシング ステート
  • カリング ステート
  • 深度バッファリング ステート
  • フォグ ステート
  • ライティング ステート
  • アウトラインおよび塗りつぶしステート
  • 頂点単位のカラー ステート
  • プリミティブ クリッピング ステート
  • シェーディング ステート
  • ステンシル バッファ ステート
  • テクスチャ ラッピング ステート


レンダリング ステートについて

デバイス レンダリング ステートは、Microsoft® Direct3D® デバイスのラスタ化モジュールの動作を制御する。レンダリング ステートの属性、使用するシェーディング タイプ、フォグ属性、その他のラスタ化処理を変更することによって、このような動作を制御する。

Microsoft® Visual Basic® アプリケーションでは、Direct3DDevice8.SetRenderState メソッドを呼び出して、レンダリング ステートの特性を制御する。CONST_D3DRENDERSTATETYPE 列挙は、可能なレンダリング ステートをすべて指定する。アプリケーションでは、CONST_D3DRENDERSTATETYPE 列挙の値を第 1 パラメータとして SetRenderState メソッドに渡す。

固定機能による頂点処理は、SetRenderState メソッドと以下のデバイス レンダリング ステートによって制御される。プログラムされた頂点シェーダを使用しても、これらの制御の多くは何も影響を受けない。

  • D3DRS_SPECULARENABLE
  • D3DRS_FOGSTART
  • D3DRS_FOGEND
  • D3DRS_FOGDENSITY
  • D3DRS_RANGEFOGENABLE
  • D3DRS_LIGHTING
  • D3DRS_AMBIENT
  • D3DRS_FOGVERTEXMODE
  • D3DRS_COLORVERTEX
  • D3DRS_LOCALVIEWER
  • D3DRS_NORMALIZENORMALS
  • D3DRS_DIFFUSEMATERIALSOURCE
  • D3DRS_SPECULARMATERIALSOURCE
  • D3DRS_AMBIENTMATERIALSOURCE
  • D3DRS_EMISSIVEMATERIALSOURCE
  • D3DRS_VERTEXBLEND

また、固定機能頂点処理パイプラインでは、以下のメソッドを使用して、トランスフォーム、マテリアル、およびライティングを設定する。

  • Direct3DDevice8.SetTransform
  • Direct3DDevice8.SetMaterial
  • Direct3DDevice8.SetLight
  • Direct3DDevice8.LightEnable

注 ピクセル パイプライン内でのスペキュラ色の追加は、D3DRS_SPECULARENABLE が制御する。D3DRS_FOGSTART、D3DRS_FOGEND、おおよび D3DRS_FOGDENSITY は、ピクセル フォグ濃度計算の開始、終了、および濃度を制御する。


アルファ ブレンディング ステート

色のアルファ値は透明度を制御する。アルファ ブレンディングを有効にすると、あるサーフェスの色、マテリアル、およびテクスチャを透明度とブレンドして、ほかのサーフェスに適用できる。

詳細については、「アルファ テクスチャ ブレンディング」および「マルチ テクスチャ ブレンディング」を参照すること。

Microsoft® Visual Basic® アプリケーションでは、D3DRS_ALPHABLENDENABLE レンダリング ステートを使用してアルファ透明ブレンディングを有効にする。Microsoft® Direct3D® API では、さまざまな種類のアルファ ブレンディングを使用できる。ただし、ユーザーの 3D ハードウェアが Direct3D で可能なブレンディング ステートのすべてに対応するとは限らないので注意が必要である。

実行されるアルファ ブレンディングの種類は、D3DRS_SRCBLEND および D3DRS_DESTBLEND レンダリング ステートによって異なる。転送元および転送先のブレンディング ステートはペアで使用する。次のコードは、転送元のブレンディング ステートを D3DBLEND_SRCCOLOR に設定し、転送先のブレンディング ステートを D3DBLEND_INVSRCCOLOR に設定する方法を示している。

' このサンプル コードでは、d3dDevice に Direct3DDevice8 オブジェクトへの
' 有効な参照が格納されていると仮定している。

' 転送元のブレンディング ステートを設定する。
d3dDevice.SetRenderState D3DRS_SRCBLEND, D3DBLEND_SRCCOLOR

' 転送先のブレンディング ステートを設定する。
d3dDevice.SetRenderState D3DRS_DESTBLEND, D3DBLEND_INVSRCCOLOR

上のサンプル コードに示す呼び出しの結果、Direct3D は転送元カラー (現在の位置でレンダリングされるプリミティブの色) と転送先カラー (フレーム バッファ内の現在の位置の色) の間で線形ブレンディングを実行する。この処理によって、色合いを持つガラスのような外観になる。転送先オブジェクトの色の一部は、転送元オブジェクトから伝わったように見える。その他の色は吸収されたように見える。

転送元および転送先のブレンディング ステートの設定を変えると、霧やほこりの中でオブジェクトが輝いているような外観になる。たとえば、アプリケーションで、炎、電磁力界、プラズマ光線、またはぼんやりした中で輝いているようなオブジェクトをモデリングする場合、転送元および転送先のブレンディング ステートを D3DBLEND_ONE に設定する。

また、アルファ ブレンディングは 3D シーンのライティングを制御する。これはライト マッピングと呼ばれることもある。転送元のブレンディング ステートを D3DBLEND_ZERO に設定し、転送先のブレンディング ステートを D3DBLEND_SRCALPHA に設定すると、転送元のアルファ情報に従ってシーンが暗くなる。転送元のプリミティブは、フレーム バッファの内容をスケーリングするライト マップとして使用され、必要に応じてシーンを暗くする。これによって、モノクロのライト マッピングが生成される。

カラー ライト マッピングは、転送元のアルファ ブレンディング ステートを D3DBLEND_ZERO に設定し、転送先のブレンディング ステートを D3DBLEND_SRCCOLOR に設定することで実現できる。


アルファ テスティング ステート

Microsoft® Visual Basic® で記述されたアプリケーションでは、アルファ テスティングを使用して、いつピクセルをレンダリング ターゲット サーフェスに書き込むかを制御する。D3DRS_ALPHATESTENABLE レンダリング ステートを使用することにより、アプリケーションでは、アルファ テスト関数に基づいて各ピクセルをテストできるように現在の Microsoft® Direct3D® デバイスを設定する。テストが成功すると、ピクセルがサーフェスに書き込まれる。テストが失敗すると、ピクセルは無視される。アルファ テスト関数は、D3DRS_ALPHAFUNC レンダリング ステートで選択する。D3DRS_ALPHAREF レンダリング ステートを使用することにより、アプリケーションでは、比較するすべてのピクセルに参照アルファ値を設定する。

アルファ テスティングは、通常、透明に近いオブジェクトをラスタ化する際のパフォーマンスを改善するために使用する。ラスタ化するカラー データが指定のピクセル (D3DPCMPCAPS_GREATEREQUAL) よりも不透明に近い場合、ピクセルが書き込まれる。そうでない場合は、ラスタライザはピクセルを無視し、2 色のブレンドに必要な処理を省略する。次のサンプル コードは、指定された比較関数がサポートされているかどうかを調べている。サポートされている場合は、レンダリングのパフォーマンス改善に必要な比較関数のパラメータを設定する。

' このサンプル コードでは、d3dDeviceDesc は、
' 前の Direct3D8.GetDeviceCaps の呼び出しによって格納された
' D3DCAPS8 型であると仮定している。
If (Caps.AlphaCmpCaps And D3DPCMPCAPS_GREATEREQUAL) Then
    Call dev.SetRenderState(D3DRS_ALPHAREF, &H1)
    Call dev.SetRenderState(D3DRS_ALPHATESTENABLE, True)
    Call dev.SetRenderState(D3DRS_ALPHAFUNC, D3DCMP_GREATEREQUAL)
End If

' 比較関数がサポートされていない場合にもレンダリングを実行する。
' ただし、パフォーマンスは改善されない。

すべてのハードウェアがアルファ テスティング機能をサポートしているわけではない。デバイス機能を調べるには、Direct3D8.GetDeviceCaps メソッドを呼び出す。デバイス機能を取得した後、使用する比較関数の関連する D3DCAPS8 型の AlphaCmpCaps メンバを調べる。AlphaCmpCaps メンバが D3DPCMPCAPS_ALWAYS 能力のみ、または D3DPCMPCAPS_NEVER 能力のみ含んでいる場合、ドライバはアルファ テストをまったくサポートしていない。


アンビエント ライト ステート

アンビエント ライトとは、全方向から照射する環境光である。

Microsoft® Direct3D® のアンビエント ライトの使用に関する特定の情報については、「ダイレクト ライトとアンビエント ライトの比較」および「Direct3D のライティングにおける数学的計算」を参照すること。

Microsoft Visual Basic®; アプリケーションでアンビエント ライトの色を設定するには、Direct3DDevice8.SetRenderState メソッドを呼び出し、列挙値 D3DRS_AMBIENT を第 1 パラメータとして渡す。第 2 パラメータはカラー値である。デフォルト値はゼロである。

' このサンプル コードでは、D3DDevice に Direct3DDevice8 オブジェクトへの
' 有効な参照を格納していると仮定している。

' アンビエント ライトを設定する。
Call D3DDevice.SetRenderState(D3DRS_AMBIENT, &H202020)


アンチエイリアシング ステート

アンチエイリアスとは、線とエッジをスクリーン上でより滑らかに表示する方法である。Microsoft® Direct3D® がサポートするアンチエイリアシングには、エッジ アンチエイリアシングおよびフルシーン アンチエイリアシングの 2 種類がある。

これらのテクニックの詳細については、「アンチエイリアシング」を参照すること。

デフォルトでは、Direct3D はアンチエイリアシングを実行しない。エッジ アンチエイリアシング (第 2 レンダリング パスが必要) を有効にするには、D3DRS_EDGEANTIALIAS レンダリング ステートを TRUE に設定する。エッジ アンチエイリアシングを無効にするには、D3DRS_EDGEANTIALIAS を FALSE に設定する。

フルシーン アンチエイリアシングを有効にするには、D3DRS_MULTISAMPLEANTIALIAS を TRUE に設定する。フルシーン アンチエイリアシングを無効にするには、D3DRS_MULTISAMPLEANTIALIAS を FALSE に設定する。


カリング ステート

Microsoft® Direct3D® は、プリミティブをレンダリングするときにプリミティブの背面をカリングする。

Microsoft Visual Basic® アプリケーションでカリング モードを設定するには、CONST_D3DCULL 列挙のメンバを設定できる D3DRS_CULLMODE レンダリング ステートを使用する。デフォルトでは、反時計回りの頂点を持つ背面をカリングする。

次のサンプル コードは、時計回りの頂点を持つ背面をカリングするカリング モードを設定する処理を示している。

' このサンプル コードでは、d3dDevice が Direct3DDevice8 オブジェクトへの
' 有効な参照を格納していると仮定している。

' カリング ステートを設定する。
Call d3dDevice.SetRenderState(D3DRENDERSTATE_CULLMODE, D3DCULL_CW)


深度バッファリング ステート

深度バッファリングとは、隠線および隠面を削除する方法である。デフォルトでは、Microsoft® Direct3D® で深度バッファリングは使用されない。

深度バッファの概要については、「深度バッファとは」を参照すること。

Microsoft Visual Basic® アプリケーションでは、CONST_D3DZBUFFERTYPE 列挙のメンバのいずれかを使用して新しいステート値を指定することで、D3DRS_ZENABLE レンダリング ステートで深度バッファリング ステートを更新する。

Direct3D による深度バッファへの書き込みを防止する必要がある場合は、D3DRS_ZWRITEENABLE レンダリング ステートを使用し、Direct3DDevice8.SetRenderState の呼び出しの第 2 パラメータとして D3DZB_FALSE を指定する。

次の Visual Basic コードは、z バッファリングが有効になるように深度バッファ ステートを設定する方法を示している。

' このコード例では、d3dDevice が Direct3DDevice8 オブジェクトへの
' 有効な参照を格納していると仮定している。

' z バッファリングを有効にする。
Call d3dDevice.SetRenderState(D3DRS_ZENABLE, D3DZB_TRUE)

アプリケーションでは、また、D3DRS_ZFUNC レンダリング ステートを使用して、深度バッファリングの実行時に Direct3D で使用する比較関数を制御できる。

z バイアスとは、互いの深度値が同じであっても、一方のサーフェスを他方のサーフェスより手前に表示する方法である。このテクニックは、さまざまなエフェクトを期待できる。一般的な例として、壁に影を付ける場合を考える。影も壁も深度値は同じである。しかし、どうしても壁に影を付けようとする場合がある。このような場合、影に z バイアスを適用することで、壁の上に影を適切に表示できる (「D3DRS_ZBIAS」を参照すること)。


フォグ ステート

フォグ エフェクトを使用すると、3D シーンを一層リアルに表現できる。フォグ エフェクトは、霧のシミュレーション以外にも使用できる。フォグ エフェクトで遠くの景色をぼかすことができる。これは実際のことを表現している。つまり、オブジェクトは遠く離れるにしたがって、その細部が不明瞭になっていく。

アプリケーションでのフォグの使用の詳細については、「フォグ」を参照すること。

Microsoft® Visual Basic® アプリケーションでは、デバイス レンダリング ステートを介してフォグを制御する。CONST_D3DRENDERSTATETYPE 列挙型には、ピクセル (テーブル) または頂点フォグのいずれが使用されているか、その色、システムが適用するフォグ公式、その公式のパラメータなどを制御するステートが含まれる。

フォグを有効にするには、D3DRS_FOGENABLE レンダリング ステートを TRUE に設定する。フォグ カラーは、D3DRS_FOGCOLOR レンダリング ステートを使用することによって、任意のカラーに設定できる (フォグ カラーのアルファ成分は無視される)。

D3DRS_FOGTABLEMODE および D3DRS_FOGVERTEXMODE レンダリング ステートは、フォグの計算に適用されるフォグ公式を制御し、適用されるフォグの種類を間接的に制御する。この両方のレンダリング ステートは、CONST_D3DFOGMODE 列挙のメンバのいずれかに設定できる。レンダリング ステートのいずれかを D3DFOG_NONE に設定すると、それに応じてピクセルまたは頂点フォグが無効になる。両方のレンダリング ステートが有効なモードに設定されている場合は、ピクセル フォグ エフェクトのみ適用される。

D3DRS_FOGSTART および D3DRS_FOGEND レンダリング ステートは、D3DFOG_LINEAR モード用のフォグ公式パラメータを制御する。D3DRS_FOGDENSITY レンダリング ステートは、指数フォグ モードのフォグ濃度を制御する。

詳細については、「フォグ パラメータ」を参照すること。


ライティング ステート

Microsoft® Direct3D® のジオメトリ パイプラインを使用するアプリケーションでは、ライティング計算を有効または無効にできる。頂点法線を含む頂点にのみライティングが正しく適用される。頂点法線がない場合は、すべてのライティング計算で 0 の内積が使用される。したがって、法線を使用しない頂点にはライティングが適用されない。

詳細については、「Direct3D のライティングにおける数学的計算」を参照すること。

アプリケーションで Direct3D のライティングを有効にするには、D3DRS_LIGHTING レンダリング ステートを TRUE (デフォルト値) に設定し、無効にするには FALSE に設定する。

ライティング レンダリング ステートは、頂点バッファ内の頂点で可能なライティング計算にはまったく依存しない。Direct3DDevice8.ProcessVertices メソッドは、頂点処理の際にライティング計算を制御する、独自のフラグを受け取る。


アウトラインおよび塗りつぶしステート

テクスチャが適用されていないプリミティブは、マテリアルによって指定される色、または頂点に指定された色があれば、そのいずれかでレンダリングされる。プリミティブを塗りつぶす方法は、CONST_D3DFILLMODE 列挙型で定義される値を D3DRS_FILLMODE レンダリング ステートに指定して選択できる。

アプリケーションでディザリングを有効にするには、第 1 パラメータとして D3DRS_DITHERENABLE 列挙値を Direct3DDevice8.SetRenderState に渡す必要がある。ディザリングを有効にするには第 2 パラメータを TRUE に設定し、無効にするには FALSE に設定する。

線の最後のピクセルを描画すると周囲のプリミティブと重なり、見た目が悪くなることがある。これは、D3DRS_LASTPIXEL 列挙値を使用して制御できる。ただし、この設定を変更するときは注意が必要である。場合によっては、最後のピクセルを描画しないようにするとプリミティブ間に隙間が生じ、見苦しくなることがある。

デフォルトでは、Microsoft®Direct3D® デバイスはプリミティブに実線のアウトラインを使用する。アウトライン パターンは、D3DLINEPATTERN 型を使用して変更できる。詳細については、「D3DRS_LINEPATTERN レンダリング ステート」を参照すること。


頂点単位のカラー ステート

以下の頂点では、色情報と法線情報を同時に持つことはできない。

  • D3DLVERTEX
  • D3DLVERTEX2
  • D3DTLVERTEX
  • D3DTLVERTEX2
  • D3DVERTEX
  • D3DVERTEX2

デフォルトのシェーディング モードはグーロー シェーディングで、このモードは頂点の色情報と法線情報の両方に依存するため、Microsoft® Direct3D® では定義済みの頂点の種類ではライティング計算に頂点カラーを使用しない。

しかし、柔軟な頂点フォーマット (FVF) を使用すると、頂点は色情報と法線情報の両方を持てる。デフォルトでは、この情報を使用してライティング計算が実行される。アプリケーションで頂点カラー ライティング情報の使用を無効にするには、Direct3DDevice8.SetRenderState を呼び出し、第 1 パラメータとして D3DRS_COLORVERTEX を渡す。第 2 パラメータを FALSE に設定すると頂点カラー ライティングが無効になり、TRUE に設定すると有効になる。

頂点単位のカラーが有効なっている場合、アプリケーションでは、頂点の色情報の情報ソースを設定できる。D3DRS_AMBIENTMATERIALSOURCE、D3DRS_DIFFUSEMATERIALSOURCE、D3DRS_EMISSIVEMATERIALSOURCE、および D3DRS_SPECULARMATERIALSOURCE レンダリング ステートは、それぞれ、アンビエント、ディフューズ、エミッション、および スペキュラ色の色成分ソースを制御する。これらの各レンダリング ステートは、CONST_D3DMATERIALCOLORSOURCE 列挙型のメンバに設定できる。これらの列挙型は、現在のマテリアル、ディフューズ色、またはスペキュラ色を、指定された色成分のソースとして使用するようシステムに知らせる定数を定義する。


プリミティブ クリッピング ステート

Microsoft® Direct3D® では、ビューポート外で部分的にレンダリングするプリミティブをクリッピングすることができる。Microsoft Visual Basic® の場合、Direct3D クリッピングは D3DRS_CLIPPING レンダリング ステートで制御する。このレンダリング ステートを TRUE (デフォルト値) に設定すると、プリミティブ クリッピングが有効になる。レンダリング ステートを FALSE に設定すると、Direct3D のクリッピング サービスは無効になる。

プリミティブ クリッピング レンダリング ステートは、頂点バッファ内の頂点で可能なクリッピング処理にはまったく依存しない。Direct3DDevice8.ProcessVertices メソッドは、頂点処理の際にプリミティブ クリッピングを制御する、独自のフラグを受け取る。


シェーディング ステート

Microsoft® Direct3D® では、フラット シェーディングとグーロー シェーディングの両方をサポートしている。デフォルトではグーロー シェーディングが設定される。現在のシェーディング モードを制御するため、Microsoft Visual Basic® アプリケーションでは CONST_D3DSHADEMODE 列挙のメンバを D3DRS_SHADEMODE レンダリング ステートに指定する。

次のコードは、シェーディング ステートをフラット シェーディング モードに設定する処理を示している。

' このコード例では、d3dDevice は Direct3DDevice8 オブジェクトへの
' 有効な参照であると仮定している。

' シェーディング ステートを設定する。
Call d3dDevice.SetRenderState(D3DRS_SHADEMODE, D3DSHADE_FLAT)


ステンシル バッファ ステート

アプリケーションは、ステンシル バッファを使用して、レンダリング ターゲット サーフェスにピクセルを書き込むかどうかを決める。

詳細については、「ステンシル バッファ」を参照すること。

Microsoft® Visual Basic® で記述されたアプリケーションでステンシル処理を有効または無効にするには、Direct3DDevice8.SetRenderState メソッドを呼び出す。第 1 パラメータの値として D3DRS_STENCILENABLE を渡す。ステンシル処理を有効にするには第 2 パラメータの値を TRUE に設定し、無効にするには FALSE に設定する。

Microsoft® Direct3D® のステンシル テストで使用する比較関数は、SetRenderState を呼び出して設定する。第 1 パラメータの値を D3DRS_STENCILFUNC に設定する。第 2 パラメータの値として CONST_D3DCMPFUNC 列挙のメンバを渡す。

ステンシル参照値とは、ステンシル関数がテストに使用する、ステンシル バッファ内の値である。デフォルトではステンシル参照値はゼロである。アプリケーションでは、SetRenderState を呼び出してこの値を設定できる。第 1 パラメータの値として D3DRS_STENCILREF を渡す。第 2 パラメータの値を新しい参照値に設定する。

Direct3D モジュールは、ピクセルに対するステンシル テストを実行する前に、ステンシル参照値とステンシル マスク値のビット積を計算する。その結果は、ステンシル比較関数によってステンシル バッファの内容と比較される。アプリケーションでは、SetRenderState を呼び出してステンシル マスクを設定できる。第 1 パラメータの値として D3DRS_STENCILMASK を渡す。第 2 パラメータを新しいステンシル マスクに設定する。

ステンシル テストが失敗したときの Direct3D の処理を設定するには、SetRenderState を呼び出し、第 1 パラメータとして D3DRS_STENCILFAIL を渡す。第 2 パラメータは CONST_D3DSTENCILOP 列挙のメンバでなければならない。

また、ステンシル テストは成功したが z バッファ テストが失敗したときの Direct3D の処理もアプリケーションで制御できる。SetRenderState を呼び出し、第 1 パラメータとして D3DRS_STENCILZFAIL を渡し、第 2 パラメータに CONST_D3DSTENCILOP 列挙のメンバを設定する。

さらに、アプリケーションでは、ステンシル テストと ｚ バッファ テストの両方が成功したときの Direct3D の処理も制御できる。SetRenderState を呼び出し、第 1 パラメータとして D3DRS_STENCILPASS を渡す。この場合も、第 2 パラメータは CONST_D3DSTENCILOP 列挙のメンバでなければならない。


テクスチャ ラッピング ステート

D3DRS_WRAP0 ～ D3DRS_WRAP7 レンダリング ステートは、デバイスのマルチテクスチャ カスケードの各種テクスチャに対して、テクスチャ ラッピングを制御する。これらのレンダリング ステートを、CONST_D3DWRAPFLAGS 列挙からの D3DWRAPCOORD_0、D3DWRAPCOORD_1、D3DWRAPCOORD_2、および D3DWRAPCOORD_3 の値の組み合わせに設定して、テクスチャの第 1、第 2、第 3、および第 4 方向でのラッピングを有効にできる。ゼロを設定すると、ラッピングはすべて無効になる。デフォルトでは、テクスチャ ラッピングは、すべてのテクスチャ ステージの全方向で無効になっている。

概要については、「テクスチャ ラッピング」を参照すること。


テクスチャ ステージ ステート

ここでは、テクスチャ ステージ ステートの概念と、各テクスチャ ステージ ステートの詳細について説明する。説明するトピックは、次のとおりである。

  • テクスチャ ステージ ステートについて
  • テクスチャ アドレッシング ステート
  • テクスチャ境界ステート
  • テクスチャ フィルタリング ステート
  • テクスチャ ブレンディング ステート


テクスチャ ステージ ステートについて

テクスチャ ステージ ステートは、テクスチャのスタイルおよびテクスチャ フィルタリングの方法を制御する。

Microsoft® Visual Basic® アプリケーションでは、Direct3DDevice8.SetTextureStageState メソッドを呼び出して、テクスチャ関連レンダリング ステートの特性を制御する。CONST_D3DTEXTURESTAGESTATETYPE 列挙は、可能なすべてのテクスチャ関連レンダリング ステートを指定する。アプリケーションでは、CONST_D3DRENDERSTATETYPE 列挙の値を第 1 パラメータとして SetTextureStageState メソッドに渡す。

アプリケーションでは、Direct3DDevice8.SetTexture メソッドを呼び出してステージのテクスチャを設定する。


テクスチャ アドレッシング ステート

Microsoft® Visual Basic® アプリケーションでは、D3DTSS_ADDRESSU、D3DTSS_ADDRESSV、および D3DTSS_ADDRESSW テクスチャ ステージ ステートを使用してテクスチャ アドレッシングを設定する。


テクスチャ境界ステート

Microsoft® Visual Basic® アプリケーションでは、D3DTSS_BORDERCOLOR テクスチャ ステージ ステートを使用して境界色テクスチャ アドレッシングを設定する。

詳細については、「境界色テクスチャ アドレッシング モード」を参照すること。


テクスチャ フィルタリング ステート

Microsoft® Visual Basic® アプリケーションでは、D3DTSS_MAGFILTER、D3DTSS_MINFILTER、および D3DTSS_MIPFILTER テクスチャ ステージ ステートを使用して、テクスチャ フィルタリングを制御する必要がある。


テクスチャ ブレンディング ステート

Microsoft® Visual Basic® アプリケーションでは、D3DTSS_COLOROP で定義されたテクスチャ ブレンディング ステートと D3DTSS_ALPHAOP テクスチャ ステージ ステートを使用して、テクスチャ ブレンディングを制御する。

詳細については、「マルチ テクスチャ ブレンディング」を参照すること。


ステート ブロック

ここでは、デバイス ステート ブロックの主要な概念について、およびアプリケーションでの使用方法について説明する。説明するトピックは、次のとおりである。

  • ステート ブロックについて
  • ステート ブロックの記録
  • ステート ブロックの取得
  • ステート ブロックの適用
  • 事前定義するステート ブロックの作成
  • ステート ブロックの削除


ステート ブロックについて

Microsoft® Direct3D® のステート ブロックとは、デバイス ステートのグループである。これには、レンダリング ステート、ライティングおよびマテリアル パラメータ、トランスフォーム ステート、テクスチャ ステージ ステート、およびカレント テクスチャ情報がある。ステート ブロックは、デバイスの現在のステートのスナップショットとして処理されるか、または明示的に記録される。スナップショットは、1 回の呼び出しでデバイスに適用することができる。デバイス ステート ブロックは、アプリケーションで必要となる共通した一連のステート変更を高速化するために、レンダリング デバイスで最適化することができる。また、デバイス ステート ブロックの使用により、デバイス ステートの適用を単純化することもできる。

Microsoft Visual Basic® では、ステート ブロック ハンドルを受け取るのは、Direct3DDevice8.EndStateBlock メソッドを呼び出してステート ブロックの記録を終了したとき、および Direct3DDevice8.CreateStateBlock メソッドを呼び出して事前定義されているデバイス ステート データ セットを取得したときである。


ステート ブロックの記録

Direct3DDevice8 オブジェクトには、アプリケーションからデバイス ステートの要求があったときにそのデバイス ステートをステート ブロックに記録する Direct3DDevice8.BeginStateBlock メソッドがある。BeginStateBlock メソッドは、デバイス ステートの変更をデバイスに適用するのではなく、デバイス ステートの変更をステート ブロックに記録し始める。BeginStateBlock を呼び出した後、次のメソッドの呼び出しはすべてデバイス ステート ブロックに記録される。

  • Direct3DDevice8.LightEnable
  • Direct3DDevice8.SetClipPlane
  • Direct3DDevice8.SetLight
  • Direct3DDevice8.SetMaterial
  • Direct3DDevice8.SetRenderState
  • Direct3DDevice8.SetTexture
  • Direct3DDevice8.SetTextureStageState
  • Direct3DDevice8.SetTransform
  • Direct3DDevice8.SetViewport

ステート ブロックの記録が終了したら、Direct3DDevice8.EndStateBlock メソッドを呼び出して記録の停止をシステムに知らせる。EndStateBlock メソッドは、ステート ブロックのハンドルをメソッドの戻り値に格納する。アプリケーションでは、このハンドルを使用して、必要に応じてステート ブロックをデバイスに適用したり、新しいステート データをブロックに記録したり、不要になったステート ブロックを削除することができる。

パフォーマンスに関する注意 最良の結果を得るためには、BeginStateBlock および EndStateBlock のペア間でのすべてのステート変更をグループ化する。

EndStateBlock メソッドが返すエラー コードをチェックすることが大切である。このメソッドが失敗した場合、その原因の多くはディスプレイ モードが変更されたことであると考えられる。アプリケーションのサーフェスを作成し直し、再度ステート ブロックを記録することで、このような障害からアプリケーションが回復するように設計する。


ステート ブロックの取得

Direct3DDevice8.CaptureStateBlock メソッドは、既存のステート ブロック内の値を更新してデバイスの現在のステートに反映する。このメソッドは、Token パラメータを 1 つだけ受け取る。このパラメータは、呼び出しが成功した場合にデバイスの現在のステートの取り込み先となるステート ブロックを識別する。

アプリケーションで記録済みのステート ブロックを更新して若干異なるステート設定を含める場合は、CaptureStateBlock メソッドが特に便利である。これを行うには、次のサンプル コードのように、既存のステート ブロックを適用し、必要な設定変更を行い、システムのステートをステート ブロックに取り込む。

' 変数 Token には、以前に記録されたデバイス ステート セットへの
' デバイス ステート ブロックへのハンドルが格納されている。

' 現在のステート ブロックを設定する。
Call d3dDevice.ApplyStateBlock(Token)

' 必要に応じてデバイス ステートを変更する。
.
.
.

' 修正したデバイス ステート データを既存のブロックに取り込む。
Call d3dDevice.CaptureStateBlock(Token)

CaptureStateBlock メソッドは、デバイスのステート全体を取り込むのではなく、ステート ブロック内の既存のステート値を更新するのみである。たとえば、次のサンプル コードのように、2 つの処理が記録されたステート ブロックがあるとする。

Call d3dDevice.SetRenderState(D3DRS_SHADEMODE, D3DSHADE_GOURAUD)
Call d3dDevice.SetTexture(0, Texture)

ステート ブロックが初めに記録されて以降、2 つの設定のいずれかを変更した場合、CaptureStateBlock メソッドは、ブロック内で変更されたステートのみ新しい値に更新する。


ステート ブロックの適用

Direct3DDevice8.ApplyStateBlock メソッドは、既存のステート ブロックをデバイスに適用する。ApplyStateBlock メソッドは、Token パラメータを 1 つだけ受け取る。このパラメータは、適用するステート ブロックを識別する。

注 ステート ブロックの記録中 (つまり、Direct3DDevice8.BeginStateBlock から Direct3DDevice8.EndStateBlock の呼び出しの間)、別のステート ブロックを適用することはできない。これを実行しようとすると失敗する。


事前定義するステート ブロックの作成

Direct3DDevice8.CreateStateBlock メソッドは、デバイス ステート セットの全体を含むか、あるいは頂点またはピクセル処理に関するデバイス ステートのみ含む新しいステート ブロックを作成する。CreateStateBlock メソッドは 2 つのパラメータを受け取る。第 1 パラメータは、新しいステート ブロックに取り込むステート情報の種類を識別する。第 2 パラメータは、呼び出しが成功したときに有効なステート ブロック ハンドルを受け取る変数のアドレスである。

第 1 パラメータの有効値は、CONST_D3DSTATEBLOCKTYPE 列挙で定義される。この列挙に含まれるメンバを使用して、デバイス ステート セットの全体 (D3DSBT_ALL)、あるいは点またはピクセル処理 (D3DSBT_VERTEXSTATE または D3DSBT_PIXELSTATE) に関するステートのみ取り込むことができる。次の一覧は、D3DSBT_VERTEXSTATE または D3DSBT_PIXELSTATE 値を渡したときにシステムによって取り込まれるステートを示している。

  • 頂点関連のステート (D3DSBT_VERTEXSTATE)
  • すべてのライティングのステート (有効または無効)
  • トランスフォーム行例
  • ユーザー定義クリップ面
    これらの値は、次のレンダリング ステートに対して設定される。
    D3DRS_AMBIENT

    D3DRS_AMBIENTMATERIALSOURCE

    D3DRS_CLIPPING

    D3DRS_CLIPPLANEENABLE

    D3DRS_COLORVERTEX

    D3DRS_CULLMODE

    D3DRS_DIFFUSEMATERIALSOURCE

    D3DRS_EMISSIVEMATERIALSOURCE

    D3DRS_FOGCOLOR

    D3DRS_FOGDENSITY

    D3DRS_FOGENABLE

    D3DRS_FOGEND

    D3DRS_FOGSTART

    D3DRS_FOGTABLEMODE

    D3DRS_FOGVERTEXMODE

    D3DRS_INDEXVERTEXBLENDENABLE

    D3DRS_LIGHTING

    D3DRS_LOCALVIEWER

    D3DRS_NORMALIZENORMALS

    D3DRS_POINTSCALE_A

    D3DRS_POINTSCALE_B

    D3DRS_POINTSCALE_C

    D3DRS_POINTSIZE

    D3DRS_POINTSIZE_MAX

    D3DRS_POINTSIZE_MIN

    D3DRS_POINTSCALEENABLE

    D3DRS_POINTSPRITEENABLE

    D3DRS_PATCHSEGMENTS

    D3DRS_RANGEFOGENABLE

    D3DRS_SHADEMODE

    D3DRS_SOFTWAREVERTEXPROCESSING

    D3DRS_SPECULARENABLE

    D3DRS_SPECULARMATERIALSOURCE

    D3DRS_TWEENFACTOR

    D3DRS_VERTEXBLEND

    これらの値は、次のテクスチャステージ ステートに対して設定される。
    D3DTSS_TEXCOORDINDEX

    D3DTSS_TEXTURETRANSFORMFLAGS

  • ピクセル関連のステート (D3DSBT_PIXELSTATE)
    これらの値は、次のレンダリング ステートに対して設定される。
    D3DRS_ALPHABLENDENABLE

    D3DRS_ALPHAFUNC

    D3DRS_ALPHAREF

    D3DRS_ALPHATESTENABLE

    D3DRS_COLORWRITEENABLE

    D3DRS_DESTBLEND

    D3DRS_DITHERENABLE

    D3DRS_EDGEANTIALIAS

    D3DRS_FILLMODE

    D3DRS_FOGDENSITY

    D3DRS_FOGEND

    D3DRS_FOGSTART

    D3DRS_LASTPIXEL

    D3DRS_LINEPATTERN

    D3DRS_MULTISAMPLEANTIALIAS

    D3DRS_MULTISAMPLEMASK

    D3DRS_SHADEMODE

    D3DRS_SRCBLEND

    D3DRS_STENCILENABLE

    D3DRS_STENCILFAIL

    D3DRS_STENCILFUNC

    D3DRS_STENCILMASK

    D3DRS_STENCILPASS

    D3DRS_STENCILREF

    D3DRS_STENCILWRITEMASK

    D3DRS_STENCILZFAIL

    D3DRS_TEXTUREFACTOR

    D3DRS_WRAP0 ～ D3DRS_WRAP7

    D3DRS_ZBIAS

    D3DRS_ZENABLE

    D3DRS_ZFUNC

    D3DRS_ZWRITEENABLE

    これらの値は、次のテクスチャステージ ステートに対して設定される。
    D3DTSS_ADDRESSU

    D3DTSS_ADDRESSV

    D3DTSS_ADDRESSW

    D3DTSS_ALPHAARG1

    D3DTSS_ALPHAARG2

    D3DTSS_ALPHAOP

    D3DTSS_BORDERCOLOR

    D3DTSS_BUMPENVLOFFSET

    D3DTSS_BUMPENVLSCALE

    D3DTSS_BUMPENVMAT00

    D3DTSS_BUMPENVMAT01

    D3DTSS_BUMPENVMAT10

    D3DTSS_BUMPENVMAT11

    D3DTSS_COLORARG1

    D3DTSS_COLORARG2

    D3DTSS_COLOROP

    D3DTSS_MAGFILTER

    D3DTSS_MAXANISOTROPY

    D3DTSS_MAXMIPLEVEL

    D3DTSS_MINFILTER

    D3DTSS_MIPFILTER

    D3DTSS_MIPMAPLODBIAS

    D3DTSS_TEXCOORDINDEX

    D3DTSS_TEXTURETRANSFORMFLAGS

注 CreateStateBlock メソッドが返すエラー コードをチェックすることが大切である。このメソッドが失敗した場合、その原因の多くはディスプレイ モードが変更されたことであると考えられる。アプリケーションのサーフェスを作成し直してステート ブロックを記録することで、このような障害からアプリケーションが回復するように設計する。


ステート ブロックの削除

Direct3DDevice8.DeleteStateBlock は、既存のステート ブロックを削除して、このステート ブロックで使用したメモリの割り当てを解除する。DeleteStateBlock メソッドは、そのパラメータでのみ削除するステート ブロックへのハンドルを受け取る。ステート ブロックを削除すると、そのステート ブロックへのハンドルは無効になり、以後使用することはできない。


消失したデバイス

ここでは、Microsoft® Direct3D® で消失したデバイスについて説明する。説明するトピックは、次のとおりである。

  • 消失したデバイスとは
  • 消失したデバイスへの応答
  • 消失したデバイスとロック処理
  • 消失したデバイスとリソース
  • 消失したデバイスと取得データ


消失したデバイスとは

Microsoft® Direct3D® デバイスの状態には、処理可能状態と消失状態がある。処理可能状態はデバイスの通常の状態であり、すべてのレンダリングが予測どおりに実行され表示される。フルスクリーン アプリケーションでキーボード フォーカスが消失するなどのイベントが発生してレンダリングできなくなると、デバイスは消失状態になる。消失状態の特性は、表面には何も現れずにすべてのレンダリング処理が失敗することである。つまり、レンダリング処理は失敗しているのに、レンダリング メソッドは成功コードを返すことがある。このような場合、Direct3DDevice8.Present によってエラー コード D3DERR_DEVICELOST が返される。

設計では、デバイスが消失するようなすべてのシナリオが想定されているわけではない。一般的な例としては、ユーザーが Alt + Tab キーを押したときなど、つまりシステム ダイアログが初期化されたときにフォーカスが消失する。また、電力管理イベントによって、ほかのアプリケーションがフルスクリーン処理を行うときにも発生することがある。さらに、Direct3DDevice8.Reset が失敗すると、デバイスは消失状態となる。


消失したデバイスへの応答

デバイスが消失すると、アプリケーションはそのデバイスに対して、処理可能状態に復元できるかどうかを問い合わせる。復元できない場合は、デバイスが復元できるまでアプリケーションは待機する。

復元できる場合は、アプリケーションはすべてのビデオ メモリ リソースとスワップ チェーンを破棄して、デバイスの復元に備える。次に、アプリケーションは Direct3DDevice8.Reset を呼び出す。Reset は、デバイスが消失状態のときに有効な唯一のメソッドであり、アプリケーションがデバイスを消失状態から処理可能状態に戻すことができる唯一のメソッドである。Direct3DDevice8.CreateRenderTarget や Direct3DDevice8.CreateDepthStencilSurfaceで作成されたリソースなど、D3DPOOL_DEFAULT で割り当てられたすべてのリソースをアプリケーションが解放しない限り、Reset は失敗する。

ほとんどの場合、Microsoft® Direct3D® を頻繁に呼び出してもデバイスが消失しているかどうかに関する情報は返らない。アプリケーションは、消失したデバイスの通知を受け取らなくても、Direct3DDevice8.DrawPrimitive などのレンダリング メソッドの呼び出しを続行できる。内部的には、これらの処理は、デバイスが処理可能状態にリセットされるまで破棄される。

アプリケーションは、デバイスが消失したときの処理を判定するために Direct3DDevice8.TestCooperativeLevel の戻り値を照会する。

  • メソッドが D3D_OK を返す場合、デバイスは処理可能である。
  • デバイスが消失し復元できない場合、戻り値は D3DERR_DEVICELOST になる。これは、ユーザーが Alt + Tab キーを押し、フルスクリーン デバイスのフォーカスが失われたケースである。アプリケーションの応答としては、デバイスがリセットできるまで一時停止しなければならない。TestCooperativeLevel からのリターン コードが D3DERR_DEVICENOTRESET であれば、リセットできる状態であることを示す。
  • デバイスが消失していて復元できる場合、TestCooperativeLevel からのリターン コードは D3DERR_DEVICENOTRESET である。Direct3DDevice8.Present メソッドからのリターン コードはまだ D3DERR_DEVICELOST であることに注意すること。

いずれの場合も、Reset の呼び出しにはビデオ メモリ リソースの破棄が前提条件となる。これは、デバイスが消失していない場合も同様である。


消失したデバイスとロック処理

内部的には、Microsoft® Direct3D® ではデバイスが消失してもロック処理は成功するように機能する。しかし、ロック処理時にはビデオメモリ リソースのデータが正確かどうかは保証されない。エラー コードが返らないことは保証されている。したがって、アプリケーションの記述にあたっては、ロック処理時のデバイスの消失については考慮しなくてよい。

詳細については、「消失したデバイスと取得データ」を参照すること。


消失したデバイスとリソース

リソースはビデオ メモリを消費する。消失したデバイスは、アダプタが所有するビデオ メモリから接続解除されるため、デバイスが消失したときのビデオ メモリの割り当てを保証することはできない。そのため、すべてのリソース作成メソッドは、D3D_OK が返ると成功するが実際にはダミーのシステム メモリのみを割り当てるように実装されている。すべてのビデオ メモリ リソースは、デバイスをサイズ変更する前に破棄する必要があるため、ビデオ メモリの過剰割り当ては発生しない。このようなダミー サーフェスにより、アプリケーションが Direct3DDevice8.Present を呼び出してデバイスの消失を検出するまで、ロック処理やコピー処理が正常に機能しているように見える。

ドライバが消失状態から処理可能状態に復元される前に、すべてのビデオ メモリが解放されなければならない。つまり、アプリケーションは Direct3DDevice8.CreateAdditionalSwapChain によって作成されたすべてのスワップ チェーンや D3DPOOL_DEFAULT メモリ クラスに配置されているすべてのリソースを解放しなければならないということである。アプリケーションは、D3DPOOL_MANAGED メモリ クラスや D3DPOOL_SYSTEMMEM メモリ クラスに配置されているリソースは解放する必要がない。ほかの状態データは、処理可能状態へのトランジションによって自動的に破棄される。

アプリケーションの開発にあたっては、デバイスの消失に対して 1 つのコード パスで対応することを推奨する。このコード パスは、スタートアップ時にデバイスの初期化に使用したコード パスと同一ではなくても類似するものとする。


消失したデバイスと取得データ

Microsoft® Direct3D® によってアプリケーションは、生成された画像 (または以前に描かれた画像) を、ビデオ メモリ リソースから不揮発性のシステム メモリ リソースにコピーすることができる。このような転送では転送元画像はいつでも失われる可能性があるため、Direct3D では、デバイスが消失したときはコピー処理を失敗させることができる。

このトピックは IDirect3DDevice8::UpdateTexture には適用しない。

コピー処理 Direct3DDevice8.UpdateTexture および Direct3DDevice8.CopyRects は、転送元オブジェクトが揮発性メモリ (D3DPOOL_DEFAULT) にあるときと転送先オブジェクトが不揮発性メモリ (D3DPOOL_SYSTEMMEM または D3DPOOL_MANAGED) にあるときは、D3DERR_DEVICELOST を返す。別のコピー処理 Direct3DDevice8.GetFrontBuffer は、プライマリ サーフェスからデータを取得することによって失敗する場合がある。上記のケースは、Direct3DDevice8.Present、Direct3DDevice8.TestCooperativeLevel、および Direct3DDevice8.Reset の外部で D3DERR_DEVICELOST を使用する唯一の例であることに注意すること。


Direct3D リソース

ここでは、リソースについて、またアプリケーションでのリソース使用の概要について説明する。説明するトピックは、次のとおりである。

  • リソースとは
  • リソース プロパティ
  • リソースの相互関係
  • リソースの使い方


リソースとは

リソースとは、シーンのレンダリングに使用されるテクスチャおよびバッファである。アプリケーションは、リソースを作成、ロード、コピー、および使用する必要がある。ここでは、リソースの概要と、リソースの操作手順およびメソッドについて説明する。各リソース タイプについては、「テクスチャ」、「頂点バッファ」、および 「インデックス バッファ」を参照すること。

ジオメトリ リソース Direct3DIndexBuffer8 および Direct3DVertexBuffer8 は、Direct3DResource8 クラスのメソッドを実装する。テクスチャ リソース Direct3DCubeTexture8、Direct3DTexture8、および Direct3DVolumeTexture8 は、Direct3DBaseTexture8 クラスのメソッドも実装する。


リソース プロパティ

すべてのリソースは、以下のプロパティを共有する。

  • 使用。テクスチャ、レンダリング ターゲットとして使用するなど、リソースの使用方法。
  • フォーマット。2D サーフェスのピクセル フォーマットなど、データのフォーマット。
  • プール。リソースが割り当てられるメモリ タイプ。
  • タイプ。頂点バッファ、レンダリング ターゲットなど、リソースのタイプ

リソースの使用は強制される。特定の処理にリソースを使用するアプリケーションは、リソース作成時にその処理を指定する必要がある。リソースには、以下の使用方法が定義されている。

  • D3DUSAGE_DEPTHSTENCIL
  • D3DUSAGE_DONOTCLIP
  • D3DUSAGE_DYNAMIC
  • D3DUSAGE_RTPATCHES
  • D3DUSAGE_NPATCHES
  • D3DUSAGE_POINTS
  • D3DUSAGE_RENDERTARGET
  • D3DUSAGE_SOFTWAREPROCESSING
  • D3DUSAGE_WRITEONLY

D3DUSAGE_RTPATCHES フラグ、D3DUSAGE_NPATCHES フラグ、および D3DUSAGE_POINTS フラグは、これらのバッファ内のデータがそれぞれ、三角形またはグリッドのパッチ、N パッチ、ポイント スプライト用に使用される可能性があることをドライバに示す。ホスト処理がないとハードウェアがこれらの処理を実行できない場合に、これらのフラグが提供される。したがって、CPU からアクセスできるように、ドライバはこれらのサーフェスをシステム メモリに割り当てることを希望することになる。ドライバがこれらの処理を完全にハードウェア内で行うことができれば、これらのサーフェスをビデオまたは /AGP メモリに割り当てられるので、ホストにコピーしなくて済み、パフォーマンスも 2 倍以上向上する。これらのフラグによって提供される情報が絶対に必要というわけではない。ドライバは、データに対してそのような処理が行われていることを検出でき、以降のフレームのためにバッファをシステム メモリに戻す。

利用フラグとそのフラグか関連付けられているリソースの詳細については、各リソース作成メソッドのリファレンス ページを参照すること。

リソースのサーフェス フォーマットの詳細については、「CONST_D3DFORMAT 列挙」を参照すること。

リソースのバッファを保持するメモリ クラスをプールと呼ぶ。プール値は、CONST_D3DPOOL 列挙で定義される。単一リソース (つまり、ミップマップのミップ レベル) 内に異なるオブジェクトが格納されている場合、プールをミックスすることはできない。また、リソースのプールを選択した後で変更することはできない。

リソース タイプは、アプリケーションが実行時に Direct3DDevice8.CreateCubeTexture などのリソース作成メソッドを呼び出したとき、非明示的に設定される。リソース タイプは、CONST_D3DRESOURCETYPE 列挙で定義される。アプリケーションでは、実行時にこれらのタイプを照会できるが、ほとんどのシナリオでは実行時のタイプ チェックは必要としない。


リソースの相互関係

次の図は、特定のリソースとその内容に対して、構文的に可能な処理を示している。リソースの使用方法については、「リソースの操作」を参照すること。

左から右への矢印は、ターゲット タイプがそのメソッドによって作成されたことを示し、右から左への矢印は、それらのリソースが引数としてそのメソッドに渡せることを示している。


リソースの使い方

ここでは、リソースを処理する際にアプリケーションが実行する一般的なタスクについて説明する。

  • リソースの管理
  • アプリケーション管理リソースおよび割り当て方法
  • リソースの操作
  • リソースのロック


リソースの管理

リソース管理は、リソースをシステム メモリ ストレージからデバイスがアクセス可能なストレージに移し、デバイスがアクセス可能なストレージから破棄するプロセスである。Microsoft® Direct3D® ランタイムには、LRU (least-recently-used) 優先方式に基づく独自の管理アルゴリズムがある。1 つのフレーム (Direct3DDevice8.BeginScene 呼び出しと Direct3DDevice8.EndScene 呼び出しの間) 内で、デバイスがアクセス可能なメモリに共存できるリソース数より多くのリソースが検出されると、most-recently-used 優先方式に切り替わる。

管理リソースを指定するには、作成時に D3DPOOL_MANAGED フラグを使用する。管理リソースは、デバイスの消失状態と処理可能状態との間のトランジションでも保持される。デバイスは、Direct3DDevice8.Reset 呼び出しによって復元でき、このようなリソースはアートワークに再ロードしなくても正常に機能し続ける。ただし、デバイスを破棄して作成し直す必要がある場合、D3DPOOL_MANAGED を使用して作成されたリソースはすべて作成し直す必要がある。

リソースをデフォルトのプールに配置することを指定するには、作成時に D3DPOOL_DEFAULT フラグを使用する。デフォルトのプール内のリソースは、デバイスの消失状態と処理可能状態間のトランジションでは保持されない。これらのリソースは Reset を呼び出す前に解放し、その後で作成し直す必要がある。

デバイスの消失状態の詳細については、「消失したデバイス」を参照すること。

リソース管理は、すべてのタイプおよび使用に対してサポートされているわけではないので注意すること。たとえば、D3DUSAGE_RENDERTARGET フラグで作成されたオブジェクトはサポートされていない。また、高い頻度で内容が変更されるオブジェクトに対しては、リソース管理は奨励しない。たとえば、すべてのフレームを変更する管理頂点バッファの場合、何らかのハードウェアのパフォーマンスを大きく低下させることがある。ただし、これはテクスチャ リソースに関する問題ではない。


アプリケーション管理リソースおよび割り当て方法

管理頂点バッファ リソースまたはインデックス バッファ リソースは、作成時に D3DUSAGE_DYNAMIC を指定しても、動的として宣言することはできない。このためには、頂点バッファの内容に加える変更ごとに追加コピーが必要となる。動的頂点バッファは、BSP ツリーまたはその他の可視データ構造から取得したデータだけでなく、動的ジオメトリのレンダリングで使用できる。これは、目的のフォーマットのバッファを事前に割り当てることで実現する。その後、これらのリソースは、アプリケーションのニーズをサポートするために、アプリケーションのリソース マネージャによって分割される。アプリケーションが同時に使用する異なる頂点ストライドはごくわずかしかなく、異なる頂点バッファは一意の各ストライドに対してのみ必要なので、動的頂点バッファの総数は少ない。このようにして動的リソースを管理するときは、リソースへの高頻度な要求によってアプリケーションのパフォーマンスが低下しないようにすることが大切である。

D3D 管理リソースとアプリケーション管理リソースの両方を同時に使用するときは、管理リソースを作成する前に、すべてのアプリケーション管理リソースを D3DPOOL_DEFAULT メモリに割り当てる必要がある。D3DPOOL_MANAGED メモリにリソースを割り当てた後で D3DPOOL_DEFAULT メモリにリソースを割り当てると、D3D メモリ リソースは使用可能メモリの不正確なアカウントを指定する。


リソースの操作

アプリケーションは、シーンをレンダリングするために、リソースを操作する。最初に、アプリケーションは次のメソッドを使ってテクスチャ リソースを作成する。

  • Direct3DDevice8.CreateCubeTexture
  • Direct3DDevice8.CreateTexture
  • Direct3DDevice8.CreateVolumeTexture

テクスチャ作成メソッドによって返されるテクスチャ オブジェクトは、サーフェスまたはボリュームのコンテナであり、これらのコンテナを一般にバッファと呼ぶ。リソースが所有するバッファは、リソースの使用、フォーマット、およびプールは継承するが、型は独自の型になる。詳細については、「リソース プロパティ」を参照すること。

アプリケーションでは (アートワークをロードするため)、以下のメソッドを呼び出して、格納されたサーフェスへのアクセスを取得する。詳細については、「リソースのロック」を参照すること。

  • Direct3DCubeTexture8.LockRect
  • Direct3DTexture8.LockRect
  • Direct3DVolumeTexture8.LockBox

ロック メソッドは、格納されたサーフェス (たとえば、テクスチャのミッピマップ サブレベルまたはキューブ面) およびピクセルへのリターン ポインタを指定する引数を取る。一般的なアプリケーションでは、サーフェス オブジェクトを直接使用することはない。

さらにアプリケーションは、次のメソッドを呼び出して、ジオメトリ指向のリソースを作成する。

  • Direct3DDevice8.CreateIndexBuffer
  • Direct3DDevice8.CreateVertexBuffer

アプリケーションは、次のメソッドを呼び出して、バッファ リソースをロックし、データを設定する。

  • D3DIndexBuffer8SetData
  • D3DVertexBuffer8SetData

これらのリソースを Microsoft® Direct3D® ランタイムで管理しているアプリケーションの場合、リソースの作成プロセスはここで終了する。それ以外のアプリケーションでは、Direct3DDevice8.UpdateTexture を呼び出して、システム メモリ リソースのデバイス アクセス可能なリソース (ハードウェア アクセラレータが使用できる) への移動を管理する。

リソースからレンダリングした画像を提示するため、アプリケーションにはカラー バッファと深度ステンシル バッファも必要である。一般的なアプリケーションの場合、カラー バッファはデバイスのスワップ チェーン (バック バッファ サーフェスの集合体) が所有し、デバイスによって非明示的に作成される。深度ステンシル サーフェスは暗黙のうちに作成されるか、Direct3DDevice8.CreateDepthStencilSurface メソッドを使用して明示的に作成される。アプリケーションは Direct3DDevice8.SetRenderTarget を呼び出し、デバイスとその深度およびカラー バッファとを関連付ける。

最終的画像の提示については、「シーンのプレゼンテーション」を参照すること。


リソースのロック

リソースをロックすると、ストレージへの CPU アクセスが許可される。リソースには、次のロッキング メソッドが定義されている。

  • D3DLOCK_DISCARD
  • D3DLOCK_READONLY
  • D3DLOCK_NOOVERWRITE
  • D3DLOCK_NOSYSLOCK
  • D3DLOCK_NO_DIRTY_UPDATE

ロッキング フラグおよびロッキング フラグと特定のリソースとの関係については、各リソース ロッキング メソッドのリファレンス ページを参照すること。アプリケーション開発者は、D3DLOCK_DISCARD、D3DLOCK_READONLY、および D3DLOCK_NOOVERWRITE フラグは単なるヒントにすぎないことに注意すること。ランタイムでは、アプリケーションがこれらのフラグに指定されている機能に従っているかどうかのチェックは行われない。D3DLOCK_READONLY を指定しながらリソースに書き込みを行った場合、予期できない結果が発生する。D3DUSAGE_WRITEONLY を指定した後でリソースから読み込みを行った場合、パフォーマンスが大きく低下することが予想される。一般に、ロッキング利用フラグを含めロッキング フラグに対する処理が、将来使用できるかは保証されず、現在においても今後においてもパフォーマンスの大幅な低下をもたらす可能性がある。

ロック処理の後にはロック解除処理を行う。たとえば、テクスチャをロックした後、アプリケーションはロックされたテクスチャのロックを解除して、そのテクスチャへの直接アクセスを放棄する。プロセッサ アクセスを許可するだけでなく、ロック持続中は、そのリソースにかかわるほかのすべての処理が順番に並べられる。オーバーラップしない領域であっても、リソースに対して 1 つのロックのみが許可され、サーフェス上にロック処理が行われている間は、そのサーフェスでのアクセラレータ処理は実行できない。

各リソース インターフェイスには、格納されているバッファをロックするためのメソッドがある。また、各テクスチャ リソースは、リソースのサブポーションをロックできる。2 次元リソース (サーフェス) では、サブ矩形をロックすることができ、ボリューム リソースでは、サブボリュームまたはボックスをロックすることができる。各ロッキング メソッドは、リソースを戻すストレージへのポインタと、データの行間隔または平面間隔 (リソース タイプによって異なる) を表す値を返す。詳細については、リソース インターフェイスのメソッド リストを参照すること。返されるポインタは、常に、ロックされたサブリージョンの左上のバイトを指す。

インデックス バッファや頂点バッファを操作する場合は、複数のロック呼び出しが行えるが、ロック呼び出しの数とロック解除呼び出しの数が一致している必要がある。

符号化された 4 × 4 ブロックにピクセルを格納する圧縮したテクスチャ フォーマットの DXT セットは、4 × 4 の境界でのみロックすることができる。


サーフェス

ここでは、Microsoft® Direct3D® サーフェイスについて説明する。説明するトピックは、次のとおりである。

  • サーフェスの基本概念
  • ガンマ コントロール
  • サーフェス メモリへの直接アクセス
  • プライベート サーフェス データ


サーフェスの基本概念

ここでは、Microsoft® Direct3D® サーフェスに関する基本概念について説明する。説明するトピックは、次のとおりである。

  • サーフェス インターフェイス
  • 幅とピッチ
  • サーフェス フォーマット
  • フリッピング サーフェス
  • サーフェスへのコピー


サーフェス インターフェイス

サーフェスは、ディスプレイ メモリの線形領域を表している。通常、サーフェスはディスプレイ カードのディスプレイ メモリに常駐しているが、システム メモリに存在することもできる。サーフェス オブジェクトは、Direct3DSurface8 オブジェクト内に含まれている。

Direct3DSurface8 クラスを取得するには、次のいずれかのメソッドを呼び出す。

  • Direct3DCubeTexture8.GetCubeMapSurface
  • Direct3DDevice8.CreateDepthStencilSurface
  • Direct3DDevice8.CreateImageSurface
  • Direct3DDevice8.CreateRenderTarget
  • Direct3DDevice8.GetBackBuffer
  • Direct3DDevice8.GetDepthStencilSurface
  • Direct3DDevice8.GetFrontBuffer
  • Direct3DDevice8.GetRenderTarget
  • Direct3DSwapChain8.GetBackBuffer

ｷ Direct3DTexture8.GetSurfaceLevel

Direct3DSurface8 オブジェクトでは、Direct3DDevice8.CopyRects メソッドによって間接的にメモリにアクセスできる。このメソッドでは、ピクセルの矩形領域をある Direct3DSurface8 オブジェクトから別の Direct3DSurface8 オブジェクト上の指定した別の矩形領域にコピーすることができる。さらに、サーフェス オブジェクトにはディスプレイ メモリに直接アクセスするメソッドもある。たとえば、Direct3DSurface8.LockRect メソッドを使用して、ディスプレイ メモリの矩形領域をロックすることができる。重要なことは、サーフェス上のロックした矩形領域を操作した後で、Direct3DSurface8.UnlockRect を呼び出すことである。


幅とピッチ

幅とピッチという単語からある程度想像できるが、非常に重要な、そして明らかに異なる意味がある。したがって、その意味と Microsoft®Direct3D® で幅とピッチの記述に使用する値の判断方法を理解する必要がある。

Direct3D では、D3DSURFACE_DESC 型を使ってサーフェスを記述する情報を伝達する。ほかにも、このディメンジョンのメモリ内での表示方法と同様に、この構造体はサーフェスのディメンジョンの情報を含むために定義される。この構造体では Height メンバと Width メンバを使い、サーフェスの論理的なディメンジョンを記述する。両方のメンバはピクセル単位で測定される。そのため、640 × 480 のサーフェスに対する Height 値と Width 値は、8 ビットのサーフェスか 24 ビットの RGB サーフェスかに関係なく同じになる。

Direct3DSurface8.LockRect メソッドを使ってサーフェスをロックすると、このメソッドはサーフェスのピッチとロックされたビットへのポインタを含む D3DLOCKED_RECT 構造体にデータを設定する。Pitch メンバの値は、サーフェスのメモリ ピッチ (または、ストライドと呼ばれる) を記述する。ピッチは、2 つのメモリ アドレス間 (あるビットマップ ラインの始点と次のビットマップ ラインの始点) の距離であり、単位はバイトである。ピッチはピクセルではなくバイト単位で測定されるために、640 × 480 × 8 のサーフェスは、異なるピクセル フォーマットの同じディメンジョンのサーフェスよりも非常に異なるピッチの値を持つ。さらに、ピッチの値は Direct3D がキャッシュとして確保するバイトを反映することもあるので、単にピッチをピクセル単位のバイト数を掛けた幅であると仮定することはできない。次の図は、幅とピッチの違いを示している。

上記の図では、フロント バッファとバック バッファはどちらも 640 × 480 × 8 で、キャッシュは 384 × 480 × 8 である。

サーフェス メモリに直接アクセスする場合のみ、ピッチの値が役立つ。たとえば、LockRect メソッドを呼び出した後に、関連付けられた D3DLOCKED_RECT 構造体の pBits メンバには、そのサーフェスのロックされた領域の左上ピクセルのアドレスが含まれ、Pitch メンバはサーフェス ピッチとなる。ピクセル単位のバイト数により、サーフェス ポインタをインクリメントしたりデクリメントすることで、左右にピクセルにアクセスできる。また、ピッチの値を現在のサーフェス ポインタに追加したり、またはそのポインタから減じたりすると、上下に移動できる。

サーフェスに直接アクセスする場合、サーフェスのディメンジョンに対して割り当てられたメモリの範囲内に置くことと、キャッシュに対して確保されたあらゆるメモリの外に置くことに注意する。さらに、サーフェスのポインタだけをロックする場合、サーフェスをロックするときに指定する矩形の範囲内に置かなくてはならない。これに従わないと、予測不可能な結果が生じる。サーフェス メモリに直接レンダリングするときは、LockRect メソッドが返すピッチを常に使用する。単に、ディスプレイ モードに基づくピッチを仮定して使用してはならない。ほかの原因により正常に動作しなくなったいくつかのディスプレイ アダプタ上でアプリケーションが動作する場合、問題が生じる可能性がある。

詳細については、「サーフェス メモリへの直接アクセス」を参照すること。


サーフェス フォーマット

サーフェス フォーマットは、サーフェス メモリ中の各ピクセルのデータをどのように判断するかを指示する。Microsoft®Direct3D® は、D3DSURFACE_DESC 構造体の CONST_D3DFORMAT メンバを使用してサーフェス フォーマットを記述する。Direct3DSurface8.GetDesc メソッドを呼び出すことによって、既存のサーフェスのフォーマットを取得することができる。


フリッピング サーフェス

Microsoft® Direct3D® アプリケーションは、通常、バック バッファにアニメーションのフレームを生成し、連続して提示することで、アニメーションを表示する。バック バッファはスワップ チェーンに分割される。スワップ チェーンとは、スクリーンに順に “フリップ” する一連のバッファのことである。このスワップ チェーンを使用すると、メモリ内のあるシーンをレンダリングし、レンダリングが完了したらそのシーンをスクリーンにフリップできる。これで、テアリングと呼ばれる現象を防ぎ、より滑らかなアニメーションが得られる。

Direct3D で作成された各デバイスは、スワップ チェーンを少なくとも 1 つは持っている。最初の Direct3D デバイスを初期化するときに、スワップ チェーン内にあるバック バッファの数を Direct3D に指示する D3DPRESENT_PARAMETERS 構造体の BackBufferCount メンバを設定する。Direct3D8.CreateDevice を呼び出し、次に、Direct3D デバイスおよび対応するスワップ チェーンを作成する。

Direct3DDevice8.Present メソッドを用いてサーフェス フリッピング処理を要求する場合、フロント バッファとバック バッファに対するサーフェス メモリへのポインタはスワップされる。フリッピングは、サーフェス メモリをコピーすることではなく、メモリを参照するためにディスプレイ デバイスの使用するポインタを切り替えることで実行される。フリッピング チェーンにフロント バッファと 1 つ以上のバック バッファがある場合、次の図に示すように、ポインタは循環的パターンで切り替えられる。

デバイスの追加スワップ チェーンを作成するには、Direct3DDevice8.CreateAdditionalSwapChain を呼び出す。アプリケーションはビューごとに 1 つのスワップ チェーンを作成し、そのスワップ チェーンを特定のウィンドウに関連付ける。アプリケーションでは、各スワップ チェーンのバック バッファに画像をレンダリングし、次にそれを個別に提示する。CreateAdditionalSwapChain は、D3DPRESENT_PARAMETERS 型を受け取り、Direct3DSwapChain8 オブジェクトを返す。次に、Direct3DSwapChain8.Present を使用して、次のバック バッファの内容をフロント バッファに表示する。各デバイスはフルスクリーン スワップ チェーンを 1 つしか持てないことに注意すること。

特定のバック バッファへアクセスするには、Direct3DDevice8.GetBackBuffer メソッドまたは Direct3DSwapChain8.GetBackBuffer メソッドを呼び出す。これらのメソッドは、返されるバック バッファ サーフェスを表す Direct3DSurface8 オブジェクトを返す。

Direct3D は、サーフェス自体をスワップするのではなく、スワップ チェーン内のサーフェス メモリ ポインタをスワップすることで、サーフェスのフリッピングを行うことを思い出すこと。つまり、次に表示されるバック バッファに対して常にレンダリングするということである。

ディスプレイ アダプタ ドライバによって行われる "フリッピング処理" と、D3DSWAPEFFECT_FLIP を使用して作成されたスワップ チェーンに適用される "Present" 処理には、明らかな違いがあることに注意することが大切である。

一般に "フリップ" という用語は、ディスプレイ アダプタがその出力信号を生成するために使用するビデオ メモリのアドレス範囲を変更する処理のことであり、これによって隠しバック バッファの内容が表示される。DirectX 8 の場合、この用語は、D3DSWAPEFFECT_FLIP スワップ エフェクトで作成されたスワップ チェーンにおけるバック バッファのプレゼンテーションのことを表すために、より一般的に使用される。

スワップ チェーンがフルスクリーンの場合に "Present" 処理がほとんど常にフリップ処理によって実装されるとき、これらの処理はスワップ チェーンがウィンドウの際に必ずコピー処理によって実装される。さらに、ディスプレイ アダプタ ドライバは、D3DSWAPEFFECT_DISCARD、D3DSWAPEFFECT_COPY、および D3DSWAPEFFECT_COPY_VSYNC スワップ チェーンに基づくフルスクリーン スワップ チェーンに対して Present 処理を実装するためにフリッピングを使用できる。

これまでの説明は、D3DSWAPEFFECT_FLIP で作成されたフルスクリーン スワップ チェーンを使用する一般的なケースに適用される。

ウィンドウ スワップ チェーンおよびフルスクリーン スワップ チェーンの異なるスワップ エフェクトの一般的な説明については、「CONST_D3DSWAPEFFECT」を参照すること。


サーフェスへのコピー

Direct3DDevice8.CopyRects メソッドを使用するときは、転送元サーフェス上の矩形の配列または Nothing を渡して、サーフェス全体を指定する。また、転送元イメージの各矩形の左上隅がコピーされる転送先サーフェス上のポイントの配列を渡す。ByVal 0 を渡して、転送元と同じ左上隅を持つ矩形をコピーすることができる。このメソッドはクリッピングをサポートしていない。すべての転送元矩形および対応する転送先矩形が、それぞれ転送元および転送先サーフェス内に完全に含まれていない場合には、このメソッドが失敗する。このメソッドは、アルファ ブレンディング、カラー キー、およびフォーマット変換はサポートしていない。転送元サーフェスと転送先サーフェスは異ならなければならない点に注意すること。

CopyRects の例

次に示す例では、2 つの矩形が転送元サーフェスから転送先サーフェスにコピーされる。最初の矩形は、転送元サーフェス上の (0, 0, 50, 50) から転送先サーフェス上の同じ位置にコピーされ、2 番目の矩形は、転送元サーフェス上の (50, 50, 100, 100) から転送先サーフェス上の (150 ,150, 200, 200) にコピーされる。

'このコードでは、
'-d3dDevice は有効な IDirect3DDevice8 オブジェクトであり、
'-Source と Dest は有効な Direct3DSurface8 オブジェクトであると仮定している。

Dim rcSource(1) As RECT
Dim ptDest(1) As Point

rcSource(0).left = 0
rcSource(0).top = 0
rcSource(0).right= 0
rcSource(0).bottom = 0

rcSource(1).left = 50
rcSource(1).top = 50
rcSource(1).right = 100
rcSource(1).bottom = 100

ptDest(0).x = 0
ptDest(0).y = 0

ptDest(1).x = 150
ptDest(1).y = 150

d3dDevice.CopyRects Source, rcSource, 2, Dest, ptDest

Microsoft® Visual Basic® では、Microsoft Direct3D® サーフェスにイメージをコピーする場合に、次のメソッドも使用できる。

  • D3DX8.LoadSurfaceFromFile
  • D3DX8.LoadSurfaceFromFileInMemory
  • D3DX8.LoadSurfaceFromMemory
  • D3DX8.LoadSurfaceFromResource
  • D3DX8.LoadSurfaceFromSurface
  • Direct3DDevice8.CopyRects


ガンマ コントロール

ここでは、Microsoft® Direct3D® で使用されるガンマ コントロールについて説明する。説明するトピックは、次のとおりである。

  • ガンマ コントロールとは
  • ガンマ コントロールの使い方


ガンマ コントロールとは

ガンマ コントロールでは、サーフェス自体のコンテンツに影響を与えることなく、システムがサーフェスのコンテンツを表示する方法を変更できる。これらのコントロールは、Microsoft® Direct3D® がスクリーン上でレンダリングされる前にサーフェスを残すのと同様、データに適用する非常に単純なフィルタと考えられる。

ガンマ コントロールは、スワップ チェーンの単なるプロパティにすぎない。ガンマ コントロールは、システムが表示する実際のレベルにサーフェスの赤、緑、および青のレベル マップを動的に変更できる。ガンマ レベルを設定することで、エフェクトを付けるフレーム バッファに新しいイメージをコピーせずに、ユーザーのスクリーンにフラッシュ カラー (ユーザーのキャラクタを出すときの赤、キャラクタが新しいアイテムを取得するときの緑など) を適用できる。または、カラー レベルを調節して、バック バッファのイメージにカラー バイアスを適用できる。

Microsoft® Direct3D® for Microsoft DirectX® 8.0 はデバイスのプロパティとして 1 つのスワップ チェーンを持っているため、各デバイスに対して、常に少なくとも 1 つのスワップ チェーン (非明示的なスワップ チェーン) が存在する。ガンマ ランプはスワップ チェーンのプロパティなので、スワップ チェーンをウィンドウにするときはガンマ ランプを適用できる。ガンマ ランプは直ちに有効になる。VSYNC を待機することはできない。

ガンマ コントロールの使用方法の詳細については、「ガンマ コントロールの使い方」を参照すること。


ガンマ コントロールの使い方

Direct3DDevice8.SetGammaRamp メソッドと Direct3DDevice8.GetGammaRamp メソッドでは、ディスプレイに対するデジタル-アナログ コンバータ (DAC) にピクセルが送られる前に、サーフェスからピクセルの赤、緑、および青の色成分に影響を与えるランプ レベルを操作できる。

ここでは、ランプ レベルの一般的な概念と、これらのレベルの処理について説明する。説明するトピックは、次のとおりである。

  • ガンマ ランプ レベルについて
  • ガンマ ランプ サポートの検出
  • ガンマ ランプ レベルの設定と取得


ガンマ ランプ レベルについて

Microsoft® Direct3D® では、ガンマ ランプという用語は一連の値のことを表す。この一連の値は、フレーム バッファのすべてのピクセルに対して、ディスプレイに対するデジタル アナログ コンバータ (DAC) により受け取られる新しいレベルに、特定の色成分 (赤、緑、および青) のレベルをマップする値である。再マッピングは、3 つの参照テーブル (個々の色成分に対して 1 つ) により実行される。

ここではその方法について説明する。Direct3D はフレーム バッファからピクセルを取得し、その固有の赤、緑、および青の色成分でピクセルを取得する。個々のコンポーネントは 0 から 65535 までの値で表される。Direct3D は元の値を取得し、その値を使用して 256 要素配列 (ランプ) のインデックスを付ける。この配列には、個々の要素を元の要素と置き換える値を含む。Direct3D では、フレーム バッファ内の各ピクセルの各色成分に対して "参照と置き換え" のプロセスを実行し、スクリーン上のすべてのピクセルに対する最終的な色を変更する。

ランプ値のグラフを作成すると、視覚化されて容易に理解できる。次に、2 つのグラフを示す。左側のグラフは色がまったく変更されないランプを示す。右側のグラフは負のバイアスを適用する色成分に置くランプを示す。

左側のグラフの配列要素には、それらのインデックスと等しい値 (インデックス 0 には要素 0、およびインデックス 255 には 65535) が含まれる。これらの値が表示される前の入力値は変更できないため、ランプのこのタイプがデフォルトとなる。右側のグラフは、より大きな変動を示す。このランプには、最初の要素 0 から最後の要素 32768 までの値が、中間の比較的一様な範囲の値で含まれる。このエフェクトは、このランプを使用する色成分がディスプレイ上で音を消して表示される。線形グラフの利用だけに限らない。つまり、必要に応じて、アプリケーションで任意のマッピングを割り当てることができる。さらに、入力をすべてゼロに設定すると、ディスプレイから色成分を削除できる。


ガンマ ランプ サポートの検出

デバイスがスワップ チェーンの現在のプレゼンテーション モード (フルスクリーンまたはウィンドウ) においてガンマ ランプをサポートしていない場合でも、エラー値が返ることはない。アプリケーションでは、D3DCAPS8 型の Caps2 メンバの D3DCAPS2_FULLSCREENGAMMA 能力ビットおよび D3DCAPS2_CANCALIBRATEGAMMA 能力ビットを調べて、デバイスの能力および口径測定器がインストールされているかどうかを判断できる。


ガンマ ランプ レベルの設定と取得

ガンマ ランプ レベルは効果的な参照テーブルであり、Microsoft®Direct3D® が表示される新しいレベルにフレーム バッファ色成分をマップするために使用する。詳細については、「ガンマ ランプ レベルについて」を参照すること。Direct3DDevice8.SetGammaRamp メソッドおよび Direct3DDevice8.GetGammaRamp メソッドを呼び出すことにより、プライマリ サーフェスに対するランプ レベルを設定し、取得できる。SetGammaRamp は 2 つのパラメータを受け取り、GetGammaRamp は 1 つのパラメータを受け取る。SetGammaRamp の第 1 パラメータは、D3DSGR_CALIBRATE か D3DSGR_NO_CALIBRATION のいずれかである。第 2 パラメータ pRamp は、D3DGAMMARAMP 型を受け取る。D3DGAMMARAMP 型には、DWORD の 256 要素配列を 3 つ (1 つの配列ごとに赤、緑、青のガンマ ランプ) 含む。GetGammaRamp には、現在のガンマ ランプを格納する D3DGAMMARAMP 型を受け取るパラメータが 1 つある。

SetGammaRamp の第 1 パラメータに D3DSGR_CALIBRATE 値を含むと、新しいガンマレベルを設定するときに口径測定器を起動できる。ガンマ ランプをキャリブレーションするといくらかオーバーヘッドがあるので、頻繁には使えない。調整されたガンマ ランプの設定は、ディスプレイ アダプタおよびモニタにかかわらず、一貫性のある完全なガンマ値を提供する。

すべてのシステムがガンマ キャリブレーションをサポートするわけではない。ガンマ キャリブレーションをサポートするかどうかを判定するには、Direct3DDevice8.GetDeviceCaps を呼び出して、メソッドが戻った後に関連付けられた D3DCAPS8 構造体の Caps2 メンバを調べる。D3DCAPS2_CANCALIBRATEGAMMA 能力フラグが存在すると、ガンマ キャリブレーションはサポートされる。

新しいランプ レベルを設定する場合、その配列に設定したレベルはアプリケーションがフルスクリーン (排他モード) の場合にだけ使用される。アプリケーションがノーマル モードに変更されると、常にランプ レベルは側に設定され、アプリケーションがフルスクリーン モードに復帰されるときに再び取得される。


サーフェス メモリへの直接アクセス

サーフェス メモリに直接アクセスするには、Direct3DSurface8.LockRect メソッドを使う。このメソッドを呼び出す場合、RECT パラメータは、直接アクセスしようとするサーフェス上の矩形を記述する RECT 型とする。サーフェス全体をロックするには、Rect を Nothing に設定する。また、サーフェスの一部だけをカバーする RECT を指定することもできる。2 つの矩形が重ならなければ、2 つのスレッドまたは 2 つのプロセスは、サーフェスの複数の矩形を同時にロックすることができる。マルチサンプル バック バッファはロックできないことに注意すること。

LockRect メソッドは、サーフェス メモリに正しくアクセスするために必要となるすべての情報を、D3DLOCKED_RECT 型に格納する。この構造体には、ピッチに関する情報が含まれており、ロックされているビットがある。サーフェス メモリへのアクセスが終了すると、Direct3DSurface8.UnlockRect メソッドを呼び出して、ロックを解除する。

サーフェスをロックしている間、そのコンテンツを直接操作することができる。サーフェス メモリを直接レンダリングするときの一般的な問題を避けるためのヒントを、以下のリストで示す。

  • 一定のディスプレイ ピッチを仮定しない。常に、LockRect メソッドが返すピッチ情報を調べること。このピッチは、サーフェス メモリの位置、ディスプレイ カードのタイプ、Microsoft® Direct3D® ドライバのバージョンなど、さまざまな理由によって変化する。詳細については、「幅とピッチ」を参照すること。
  • ロックを解除されたサーフェスへのコピーを確認する。Direct3D コピー メソッドは、ロックされたサーフェスで呼び出されると、失敗する。
  • サーフェスがロックされている間、アプリケーションのアクティビティは制限される。
  • ディスプレイ メモリに対して連続するデータを常にコピーする Microsoft® Windows® 95 および Windows 98 では、ページ フォールト ハンドラ Vflatd.386 を使用して、バンクスイッチ メモリを使ったディスプレイ カードに対する仮想フラットフレーム バッファを実装する。このハンドラにより、これらのディスプレイ デバイスは Direct3D に連続したフレーム バッファを渡すことができる。ディスプレイ メモリに対して不連続のデータをコピーすると、コピーがメモリ バンクにスパンする場合に、システムが一時停止を起こす可能性がある。
  • D3DPOOL_DEFAULT メモリ プールに割り当てられたリソースに属するサーフェスは、ロックされない場合がある。バック バッファ サーフェス (Direct3DDevice8.GetBackBuffer および Direct3DSwapChain8.GetBackBuffer メソッドを使用してアクセスできる) をロックできるのは、スワップ チェーンが D3DPRESENTFLAG_LOCKABLE_BACKBUFFER を含めるように D3DPRESENT_PARAMETERS 構造体の Flags メンバを使用して作成されている場合だけである。


プライベート サーフェス データ

サーフェスと共にあらゆる種類のアプリケーション固有データを格納できる。たとえば、ゲームのマップを示すサーフェスには、地域情報を含む場合がある。

サーフェスでは、1 つ以上のプライベート データ バッファを所有できる。各バッファは、サーフェスにデータをアタッチする際に指定する GUID で識別される。

プライベート サーフェス データを格納するには、Direct3DSurface8.SetPrivateData メソッドを使用する。このメソッドは、サーフェスに関連付けるデータ、データ バッファのサイズ、データ用にアプリケーションで定義した DXGUID を含むバッファを渡す。

SetPrivateData はデータに対して内部バッファを割り当て、データをコピーする。その後で、転送元バッファまたはオブジェクトを安全に解放できる。内部バッファまたはインターフェイス参照は、Direct3DSurface8.FreePrivateData の呼び出し時に解放される。サーフェスが解放されると、この処理は自動的に発生する。

サーフェスに対するプライベート データを取得するには、正確なサイズのバッファを割り当て、SetPrivateData でデータに割り当てられた DXGUID を渡す Direct3DSurface8.GetPrivateData メソッドを呼び出さなくてはならない。このバッファを使用するあらゆる動的メモリの解放については、各自で責任を持つ。

割り当てるバッファのサイズがわからない場合は、最初に SizeOfData にゼロを代入して GetPrivateData を呼び出す。このメソッドが D3DERR_MOREDATA で失敗した場合、バッファに必要なバイト数を SizeOfData に返す。


ライト

ライトは、シーンのオブジェクトを照らすために使用する。ここでは、ライティング、および Microsoft® Direct3D® アプリケーションでのライトの使用方法について説明する。説明するトピックは、次のとおりである。

  • ライティングとマテリアルの概要
  • Direct3D のライティング モデルと自然光の比較
  • ライティングとマテリアルのカラー値
  • ダイレクト ライトとアンビエント ライトの比較
  • ライト オブジェクト
  • ライト プロパティ
  • ライトの使い方


ライティングとマテリアルの概要

ライティングが有効になっているとき、Microsoft® Direct3D® はレンダリングの最終段階としてシーンをラスタライズする際、シーンの光源によって生成されるライティングの色と強度や、シーンのアンビエント ライト レベルのほかにも、現在のマテリアル カラーおよび関連付けられたテクスチャ マップのテクセル、頂点のディフューズ色とスペキュラ色 (指定されている場合) の組み合わせに基づいて、レンダリングする各ピクセルの色を決める。Direct3D のライティングとマテリアルを使用するときは、Direct3D で自動的にライティングの詳細を制御するようにできる。経験を積んだユーザーであれば、必要に応じて自分でライティングを実行できる。

ライティングとマテリアルの処理方法によって、レンダリングしたシーンの表示は大きく異なる。マテリアルは、サーフェスからの反射光の状態を定義する。ダイレクト ライトとアンビエント ライト レベルは、反射光を定義する。ライティングが有効のときは、マテリアルを使用してシーンをレンダリングしなければならない。ライティングはシーンのレンダリングにおいては必須ではないが、ライティングなしでレンダリングしたシーンの細部は見えない。ライティングのないシーンをレンダリングした場合は、シーンのオブジェクトのシルエットが表示される程度である。細部は十分に表示されない。


Direct3D のライティング モデルと自然光の比較

自然界では、光源から放射された光は、何千や何百万ではないにしても、何百もの物体に反射した末にわたしたちの目に届く。光は反射するたびに、その一部が物体の表面に吸収されたり、周囲に拡散し、その残りがほかの表面や私たちに達する。この過程は、光が減衰して消えてなくなるか、またはわたしたちが光が届いたことを知覚するまで繰り返される。

自然光の動きを完全にシミュレートする計算には、あまりにも膨大な時間がかかるため、リアルタイム 3D グラフィックスで使用できないことは明白である。そこで、速度を考慮して、Microsoft® Direct3D® のライティング モデルでは自然光の動きを大まかにシミュレートする。Direct3D では、最終的な色を作成する色成分、赤、緑、および青によって光を描く。詳細については、「ライティングとマテリアルのカラー値」を参照すること。

Direct3D では、光がサーフェスに反射したとき、光の色とサーフェス自体を数学的に処理することで、最終的にスクリーンに描画される色を作成する。Direct3D で使用するアルゴリズムに関する特定の情報については、「Direct3D のライティングにおける数学的計算」を参照すること。

Direct3D のライティング モデルは、大きく分けてアンビエント ライトとダイレクト ライトの 2 つがある。これらは互いに異なる属性を持ち、サーフェスのマテリアルとの相互作用も異なる。アンビエント ライトは、方向も光源も持たず、環境内を散乱している光で、環境光とも言われる。アンビエント ライトの強度は、どの位置座標においても下位レベルに保たれる。アンビエント ライトの適切な例としては、カメラマンが使用する間接照明がある。Direct3D のアンビエント ライトには、自然光と同様、実際の方向や光源はない。あるのは色と強度のみである。実際、アンビエント ライトのレベルは、シーン内の光を発するオブジェクトとはまったく関係しない。アンビエント ライトはスペキュラ反射を起こさない。

ダイレクト ライトは、シーン内の光源が生成する光である。ダイレクト ライトには常に色と強度があり、特定の方向に進む。ダイレクト ライトは、サーフェスのマテリアルと相互作用してスペキュラ ハイライトを生み、その方向はグーロー シェーディングなどのシェーディング アルゴリズムで係数として使用される。ダイレクト ライトの反射は、シーンのアンビエント ライトのレベルに影響を与えない。シーン内のダイレクト ライトを生成する光源にはさまざまな特性があり、それによってシーンをどのように照らすかが異なる。詳細については、「ライト」を参照すること。

さらに、ポリゴンのマテリアルには、ポリゴンが光をどのように反射するかを決める特性がある。マテリアルがどのようにアンビエント ライトを反射するかを示す単一の反射特性を設定し、マテリアルのスペキュラ反射率およびディフューズ反射率を決める個々の特性を設定する。詳細については、「マテリアル」を参照すること。


ライティングとマテリアルのカラー値

Microsoft® Direct3D® には、色を記述する 4 つの成分 (赤、緑、青、およびアルファ) があり、これらを組み合わせて最終的な色が生成される。D3DCOLORVALUE 型は、これらの各成分を格納するように定義される。各メンバは、通常 0.0 と 1.0 を含む 0.0 ～ 1.0 の範囲の浮動小数点値である。ライティングとマテリアルでは、共に同じ構造体を使用して色を記述するが、構造体内で使用する値は互いに少しずつ異なる。

光源のカラー値は、光源が発する特定の光の成分の量を表す。ライティングではアルファ成分は使用しないため、赤、緑、および青成分のみ関連がある。これらの 3 つの成分は、プロジェクション モニタの赤色、緑色、および青色のレンズに例えることができる。各レンズをオフにしたり (対応するメンバに 0.0 を設定)、できるだけ明るくしたり (1.0 を設定)、その間のレベルを設定することができる。各レンズからの色を組み合わせて、最終的なライティングの色を作成する。R:1.0、G:1.0、B:1.0 の組み合わせの場合、白色光になり、R:0.0、G:0.0、B:0.0 の場合は光をまったく放射しないライティングになる。色成分を 1 つだけ放射するライティングを作成して、純粋な赤色、緑色、または青色のライティングを作ることができる。また、色成分の組み合わせによっては、黄色や紫色などの色を放射するライティングを作成することもできる。色成分値を負にして、シーンから明かりをなくすような "暗色光" を作成できる。また、成分に 1.0 より大きな値を設定して、極端に明るいライティングを作成することもできる。

一方、マテリアルの場合、カラー値はそのマテリアルを使用するサーフェスがどのくらい光の成分を反射するかを表す。マテリアルの色成分が R:1.0、G:1.0、B:1.0、A:1.0 の場合、マテリアルはすべての光を反射する。同様に、R:0.0、G:1.0、B:0.0、A:1.0 の場合は、緑色の光をすべて反射する。マテリアルに複数の反射率を指定して、さまざまなエフェクトを作成できる。詳細については、「マテリアル プロパティ」を参照すること。

アンビエント ライトのカラー値は、ダイレクト ライト光源とマテリアルに使用するカラー値とは異なる。詳細については、「ダイレクト ライトとアンビエント ライトの比較」を参照すること。


ダイレクト ライトとアンビエント ライトの比較

ダイレクト ライトとアンビエント ライトは、ともにシーン内のオブジェクトを照らすが、両者は互いに影響し合うことはなく、それぞれが持つエフェクトは大きく異なるもので、これらの操作方法についてもまったく異っている。

ダイレクト ライトは、文字どおり、ダイレクトである。ダイレクト ライトは常に方向と色を持ち、これはグーロー シェーディングなどのシェーディング アルゴリズムの係数として使用される。ライティングの種類が異なれば、ダイレクト ライトの放射も異なり、それぞれ特別な減衰エフェクトを生み出す。ダイレクト ライトのライティング パラメータ セットは、Direct3DDevice8.SetLight メソッドを呼び出して設定する。詳細については、「ライト」を参照すること。

アンビエント ライトは、シーン内のどの位置座標にもエフェクトを及ぼす。アンビエント ライトは、オブジェクトやオブジェクトのシーン内の位置座標にかかわらず、シーン全体を同じ強度の光で照らすライティングと考えることができる。アンビエント ライトはあらゆる位置に存在し、色と強度を持つのみで、位置座標や方向は持たない。アンビエント ライト レベルを設定するには、Direct3DDevice8.SetRenderState メソッドを呼び出し、State パラメータとして D3DRS_AMBIENT を指定し、Value パラメータとして目的の RGBA 色を指定する。


ライト オブジェクト

Microsoft® Direct3D® では、ポイント ライト、スポットライト、およびディレクショナル ライトの 3 種類のライトを使用する。ライト プロパティ セットを作成するときに、使用するライトの種類を選択する。ライト プロパティとそれに伴う計算上のオーバーヘッドは、ライティングの種類によって異なる。Direct3D ライティング モジュールでサポートされる、以下の光源について説明する。

  • ポイント ライト
  • スポットライト
  • ディレクショナル ライト

これらの光源とアンビエント ライト レベルを混同しないこと。詳細については、「ダイレクト ライトとアンビエント ライトの比較」、「ライト プロパティ」、および「ライトの使い方」を参照すること。


ポイント ライト

ポイント ライトは、シーン内で色と位置座標を持つが、単一の方向は持たない。次の図に示すように、ポイント ライトはすべての方向に均等に光を放つ。

ポイント ライトの例としては電球がある。ポイント ライトは減衰と範囲の影響を受け、頂点ごとにメッシュを照らす。ライティングの実行中、Microsoft® Direct3D® は、ワールド空間でのポイント ライトの位置座標とライティングする頂点の座標を使用して、ライトの方向を表すベクトルと光が進んだ距離を取得する。頂点法線に加えて、このベクトルと距離の両方を使用して、サーフェスにどのくらい光が当っているかを計算する。


スポットライト

スポットライトは、色、位置座標、および光を放射する方向を持つ。スポットライトから放射される光は、明るい内部コーンとこれより大きな外部コーンで構成される。次の図に示すように、光の強度は 2つのコーン間で減少する。

スポットライトは、フォールオフ、減衰、および範囲の影響を受ける。これらの要因は、光が各頂点まで進む距離と同様、シーン内のオブジェクトへのライティング エフェクトを計算するときに考慮に入れる。各頂点に対するこれらのエフェクトを計算する場合、Microsoft Direct3D® のすべてのライトの中でコンピュータへの負荷が最も大きいのはスポットライトである。


ディレクショナル ライト

ディレクショナル ライトは、色と方向を持ち、位置座標は持たない。これは平行な光を放射する。つまり、ディレクショナル ライトで生成された光はすべてシーン内で同じ方向に進む。ディレクショナル ライトは、太陽のような遠く離れた光源に例えることができる。ディレクショナル ライトは減衰と範囲の影響を受けないので、Microsoft® Direct3D® では指定された色と方向のみ考慮して、頂点の色を計算する。ライティング係数の個数が少ないため、ディレクショナル ライトはコンピュータへの負荷が最も軽いライトである。


ライト プロパティ

ライト プロパティは、光源の種類と色を決める。使用するライトの種類によって、ライトは減衰と範囲のプロパティやスポットライト エフェクトのプロパティを持つことができる。しかし、ライトの種類によっては使用できないプロパティもある。Microsoft® Direct3D® では、Microsoft Visual Basic® の D3DLIGHT8 型にすべての種類の光源のライト プロパティに関する情報を保持する。ここでは、すべてのライト プロパティについて説明する。説明するトピックは、次のとおりである。

  • ライトの種類
  • ライトの色
  • 頂点色
  • ライトの位置座標、範囲、および減衰
  • ライトの方向
  • スポットライト プロパティ

ライト プロパティは、光源がシーン内のオブジェクトをどのように照らすかに影響する。

詳細については、「ライトの使い方」、「ライト プロパティの設定」、および「Direct3D のライティングにおける数学的計算」を参照すること。


ライトの種類

ライトの種類プロパティは、使用する光源の種類を定義する。Microsoft Visual Basic® の場合、ライトの種類は、ライトの D3DLIGHT8 型の Type メンバに CONST_D3DLIGHTTYPE 列挙からの値を使用して設定する。Microsoft® Direct3D® には、ポイント ライト、スポットライト、およびディレクショナル ライトの 3 種類のライトがある。ライトの種類ごとに、シーン内のオブジェクトの照らし方が異なり、計算におけるオーバーヘッドのレベルも異なる。各ライトの作用に関する一般的な情報については、「ライト オブジェクト」を参照すること。


ライトの色

Microsoft® Direct3D® のライトは、システムによるライティング計算で独立して使用される、ディフューズ色、アンビエント色、およびスペキュラ色の 3 つの色を放射する。それぞれの色は、Direct3D ライティング モジュールによって組み込まれ、現在のマテリアルの色と相互作用し、最終的にレンダリングで使用される色が生成される。ディフューズ色は現在のマテリアルのディフューズ プロパティと相互作用し、スペキュラ色はマテリアルのスペキュラ属性と相互作用する、という具合に処理される。 Direct3D でのこれらの色の適用方法については、「Direct3D のライティングにおける数学的計算」を参照すること。

Microsoft Visual Basic® の場合、D3DLIGHT8 型にこれらの色を表す 3 つのメンバ Diffuse、Ambient、および Specular が含まれる。各メンバは、放射する色を定義する D3DCOLORVALUE 型である。

システムの計算負荷が比較的大きいのは、ディフューズ色である。最も一般的なディフューズ色は白色 (R:1.0 G:1.0 B:1.0) であるが、目的のエフェクトを出すために必要に応じて色を作成できる。たとえば、暖炉に赤色のライトを使用したり、"Go" になった交通信号に緑色を使用することができる。

一般には、ライトの色成分を 0.0 と 1.0 を含む 0.0 ～ 1.0 の値に設定するが、これ以外の値に設定することもできる。たとえば、すべての成分を 2.0 に設定して、"白色よりも明るい" ライトを作成できる。このような設定は、定数以外の減衰設定を使用するときには特に便利である。

Direct3D ではライトに RGBA 値を使用するが、アルファ成分は使用しない。詳細については、「ライティングとマテリアルのカラー値」を参照すること。


頂点色

一般に、マテリアル カラーはライティングに使用される。しかし、マテリアル カラー (エミッション、アンビエント、ディフューズ、およびスペキュラ) を、ディフューズ頂点カラーまたはスペキュラ頂点カラーで置き換えるよう指定できる。この指定を行うには、Direct3DDevice8.SetRenderState を呼び出して、次の表に示すデバイス ステート変数を設定する。

デバイス ステート変数 | 意味 | 型 | デフォルト
D3DRS_AMBIENTMATERIALSOURCE | アンビエント マテリアル カラーを取得する場所を定義する。 | D3DMATERIALCOLORSOURCE | D3DMCS_MATERIAL
D3DRS_DIFFUSEMATERIALSOURCE | ディフューズ マテリアル カラーを取得する場所を定義する。 | D3DMATERIALCOLORSOURCE | D3DMCS_COLOR1
D3DRS_SPECULARMATERIALSOURCE | スペキュラ マテリアル カラーを取得する場所を定義する。 | D3DMATERIALCOLORSOURCE | D3DMCS_COLOR2
D3DRS_EMISSIVEMATERIALSOURCE | エミッション マテリアル カラーを取得する場所を定義する。 | D3DMATERIALCOLORSOURCE | D3DMCS_MATERIAL
D3DRS_COLORVERTEX | 頂点カラーの使用を有効/無効にする。 | BOOL | TRUE

アルファ/透明値は常に、ディフューズ色のアルファ チャネルからのみ得られる。

フォグ値は常に、スペキュラ色のアルファ チャネルからのみ得られる。

D3DMATERIALCOLORSOURCE には、以下の値を指定することができる。

  • D3DMCS_MATERIAL – マテリアル カラーをソースとして使用
  • D3DMCS_COLOR1 - ディフューズ頂点カラーをソースとして使用
  • D3DMCS_COLOR2 – スペキュラ頂点カラーをソースとして使用


ライトの位置座標、範囲、および減衰

D3DLIGHT8 型には、Microsoft® Visual Basic® アプリケーションでライトの位置座標、範囲、および減衰プロパティを定義するために使用するメンバが含まれる。これらのプロパティは、ワールド空間でのライトの位置座標と、ライトが放射する光が距離の増加に伴ってどのように変化するかを定義する。

位置座標

ライトの位置座標は、D3DLIGHT8 型の Position メンバに D3DVECTOR 型を使用して記述する。x、y、z 座標はワールド空間にあると仮定する。ディレクショナル ライトは、位置座標プロパティを使用しない唯一のライトである。

範囲

ライトの範囲プロパティは、オブジェクトが放射した光をシーン内のメッシュが受け取れなくなるまでの、ワールド空間での距離を決める。Range メンバには、ワールド空間でのライトの最大範囲を表す浮動小数点値が含まれる。ディレクショナル ライトでは範囲プロパティは使用しない。

減衰

減衰は、範囲プロパティで指定した最大距離に近づくにつれてライトの強度がどのように減少するかを制御する。ライトの減衰は、3 つの D3DLIGHT8 メンバ、Attenuation0、Attenuation1、および Attenuation2 メンバで表す。これらのメンバには、ライトの減衰を制御する 0.0 ～ 無限大の浮動小数点値が含まれる。アプリケーションによっては、Attenuation1 メンバを 1.0 に設定し、その他のメンバを 0.0 に設定することで、ライトの強度が 1 / D として変化するようにする。ここで、D は光源から頂点までの距離である。光源ではライトの強度が最大で、そこから離れるに従って 1 / (ライトの範囲) に減少する。通常、アプリケーションでは Attenuation0 を 0.0 に設定し、Attenuation1 を定数に設定し、Attenuation2 を 0.0 に設定する。

減衰値を組み合わせて、より複雑な減衰エフェクトを出すことができる。また、減衰値を通常の範囲外の値に設定して、さらに珍しい減衰エフェクトを出すことができる。たとえば、負の減衰値を設定すると、距離が増加するに従ってライトが明るくなる。

Microsoft® Direct3D® で減衰の計算に使用する数学モデルの詳細については、「距離の増加によるライトの減衰」を参照すること。範囲プロパティと同様、ディレクショナル ライトでは減衰プロパティは使用しない。


ライトの方向

ライトの方向プロパティは、オブジェクトの放射する光がワールド空間内を進む方向を決める。方向は、ディレクショナル ライトとスポットライトでのみ使用し、ベクトルで定義する。

Microsoft® Visual Basic® アプリケーションでは、ライトの D3DLIGHT8 型の Direction メンバにライトの方向を設定する。Direction メンバは、D3DVECTOR 型である。方向ベクトルは、シーン内のライトの位置座標とは無関係に、論理原点からの距離として記述する。したがって、シーンにまっすぐに入射する (z 軸の正方向に沿って) スポットライトの方向ベクトルは、その位置座標がどこに定義されていても <0,0,1> である。同様に、シーンを真上から照らす太陽光をシミュレートするには、方向が <0,-1,0> のディレクショナル ライトを使用すればよい。必ずしも座標軸に沿って照らすライトを作成する必要がないことは明らかである。値を組み合わせたり、揃えたりして、面白い角度からライトを照らすことができる。

注 ライトの方向ベクトルを正規化する必要はないが、必ずベクトルのマグニチュードを指定すること。つまり、<0,0,0> の方向ベクトルは使用しない。


スポットライト プロパティ

Microsoft® Visual Basic® の D3DLIGHT8 型には、スポットライトでのみ使用する 3 つのメンバが含まれている。これらのメンバ (Falloff、Theta、および Phi) は、スポットライト オブジェクトの内部コーンと外部コーンの大きさを制御し、両方のコーンの間でライトがどのように減少するかを制御する。これらの特性の一般的な説明については、「スポットライト」を参照すること。

Theta 値はスポットライトの内部コーンのラジアン角度を表し、Phi 値は外部コーンのラジアン角度を表す。Falloff 値は、内部コーンの外側エッジと外部コーンの内側エッジとの間で、ライトの強度がどのように減少するかを制御する。ほとんどのアプリケーションでは、Falloff を 1.0 に設定して 2 つのコーン間でフォールオフが一様に生じるようにするが、必要に応じてこれ以外の値を設定することもできる。

フォールオフの計算において Microsoft® Direct3D® が使用する数学的モデルの詳細については、「スポットライト フォールオフ モデル」を参照すること。

次の図は、メンバの値の間にある関係と、これらの値がスポットライトの内部コーンと外部コーンに与える影響を示している。


ライトの使い方

ここでは、Microsoft® Direct3D® アプリケーションでのライトの使用方法について説明する。説明するトピックは、次のとおりである。

  • ライト プロパティの設定
  • ライトの有効/無効
  • ライト プロパティの取得


ライト プロパティの設定

Microsoft Visual Basic® アプリケーションでライト プロパティを設定するには、D3DLIGHT8 型を用意し、次に Direct3DDevice8.SetLight メソッドを呼び出す。SetLight メソッドは、デバイスがライト プロパティ セットをデバイス内部のライト プロパティのリストに配置する際のインデックスと、そのライト プロパティを定義する D3DLIGHT8 型のアドレスを受け取る。ライト プロパティの更新が必要なときは、新しい情報で SetLight を呼び出すことができる。

プロパティを割り当てられていないインデックスで SetLight メソッドを呼び出すたびに、システムはライト プロパティ セットを格納するためのメモリを割り当てる。アプリケーションでは、割り当てられているライトのサブセットを一度に有効にして、数多くのライトを設定できる。デバイスがサポートするアクティブなライトの最大数を決定するためにデバイス能力を取得するときは、D3DCAPS8 型の MaxActiveLights メンバをチェックする。ライトを使用する必要がなくなった場合は、そのライトを無効にするか、新しいライト プロパティ セットで上書きすることができる。

次のサンプル コードは、距離の増加によって減衰しない、白色のポイント ライトのプロパティを準備および設定する。

'
' このコードでは、変数 d3dDevice は、Direct3DDevice8 オブジェクトへの
' 有効な参照を格納すると仮定している。
'
Dim LightDesc As D3DLIGHT8
Dim c As D3DCOLORVALUE
Dim vPos As D3DVECTOR

' すべての放射光色に同じ色設定を使用する。
With c
    .r = 1#: .g = 1#: .b = 1#
    .a = 1# ' アルファ成分はライトに使用されない。
End With

With vPos
    .x = 0: .y = 1000: .z = -100
End With

With LightDesc
    .Type = D3DLIGHT_POINT
    .Position = vPos
    .Ambient = c: .diffuse = c: .specular = c
    .Attenuation0 = 1# ' ライトを減衰しない。
End With

d3dDevice.SetLight 0, LightDesc

ライト プロパティ セットは、再度 SetLight を呼び出していつでも更新できる。更新するライト プロパティ セットのインデックスと、新しいプロパティを含む D3DLIGHT8 型のアドレスを指定するだけである。

注 ライト プロパティ セットをデバイスに割り当てても、追加されるプロパティを持つ光源が有効になるわけではない。光源を有効にするには、デバイスに対して Direct3DDevice8.LightEnable メソッドを呼び出す。


ライトの有効/無効

シーン内の光源のライト プロパティ セットをいったん割り当てると、デバイスに対して Direct3DDevice8.LightEnable メソッドを呼び出すことで、その光源をアクティブにすることができる。新しく割り当てた光源は、デフォルトでは無効になっている。LightEnable メソッドは、2 つのパラメータを受け取る。第 1 パラメータには、メソッドで処理する光源のインデックス (0 から始まる) を設定する。第 2 パラメータには、ライトを有効にする場合は TRUE、無効にする場合は FALSE を設定する。

次のコードは、LightEnable メソッドを使用して、デバイスの光源プロパティのリスト内の最初の光源を有効にする方法を示している。

'
' このコードでは、変数 d3dDevice は、Direct3DDevice8 オブジェクトへの
' 有効な参照を格納していると仮定している。
'
On Local Error Resume Next

Call d3dDevice.LightEnable(0, True)
If Err.Number <> D3D_OK Then
    ' エラー処理コード。
End If

Direct3Ddevice8.SetLight で設定するプロパティがないライトを有効または無効にする場合、LightEnable メソッドは以下の表のプロパティを持つ光源を作成し、その光源を有効または無効にする。

メンバ | デフォルト
Type | D3DLIGHT_DIRECTIONAL
Diffuse | (R:1, G:1, B:1, A:0)
Specular | (R:0, G:0, B:0, A:0)
Ambient | (R:0, G:0, B:0, A:0)
Position | (0, 0, 0)
Direction | (0, 0, 1)
Range | 0
Falloff | 0
Attenuation0 | 0
Attenuation1 | 0
Attenuation2 | 0
Theta | 0
Phi | 0


ライト プロパティの取得

Microsoft® Visual Basic® アプリケーションで、既存の光源のプロパティを取得するには、デバイスに対して Direct3DDevice8.GetLight メソッドを呼び出す。GetLight メソッドを呼び出すとき、プロパティを取得する光源の 0 から始まるインデックスを第 1 パラメータに渡し、D3DLIGHT8 型の変数を第 2 パラメータに渡す。デバイスは、D3DLIGHT8 型に値を設定して、指定されたインデックスの光源でそのデバイスが使用するライト プロパティを記述する。

次のサンプル コードは、この処理を示している。

'
' このコードでは、変数 d3dDevice は、Direct3DDevice8 オブジェクトへの
' 有効な参照を格納すると仮定している。
'
Dim lightDesc As D3DLIGHT8

' 最初のライトについてのプロパティ情報を取得する。
Call d3dDevice.GetLight(0, lightDesc)
If Err.Number <> D3D_OK Then
    ' エラー処理コード。
End If

デバイス内で割り当てられている光源の範囲外のインデックスを指定すると、GetLight メソッドは失敗し、Err.Number の値が D3DERR_INVALIDCALL になる。


マテリアル

ここでは、マテリアルと Microsoft® Direct3D® アプリケーションでのマテリアルの使用方法について説明する。説明するトピックは、次のとおりである。

  • マテリアルとは
  • マテリアル プロパティ
  • マテリアルの使い方

デフォルトのマテリアル プロパティに関する注意 アプリケーションで、レンダリング処理にマテリアル プロパティが指定されていない場合は、デフォルトのマテリアルが使用される。デフォルトのマテリアルは、すべてのディフューズ ライト (白色など) を反射するが、アンビエント反射またはスペキュラ反射は生じず、エミッション色がない。


マテリアルとは

マテリアルは、3D シーンでポリゴンが光をどのように反射するか、またはどのように光を放射するように見えるかを指定する。本質的には、マテリアルは、Microsoft® Direct3D® がレンダリングするポリゴンについて次の情報を Direct3D に指示するプロパティの集合である。

  • ポリゴンによるアンビエント ライトとディフューズ ライトの反射方法
  • ポリゴンからのスペキュラ ハイライトの状態
  • ポリゴンが光を発しているように見せるかどうか

Microsoft® Visual Basic® で記述された、Direct3D アプリケーションでは、D3DMATERIAL8 型を使用してマテリアル プロパティを定義する。詳細については、「マテリアル プロパティ」を参照すること。


マテリアル プロパティ

マテリアル プロパティは、マテリアルのディフューズ、アンビエント反射、エミッション、およびスペキュラ ハイライト特性を詳細に指定する。Microsoft® Direct3D® は、D3DMATERIAL8 型にすべてのマテリアル プロパティを保持する。マテリアル プロパティは、そのマテリアルを使用するポリゴンをラスタ化するときに Direct3D が使用する色に影響する。スペキュラ属性を除き、各プロパティは、マテリアルが所定の種類のライトの赤、緑、および青成分をどのくらい反射するかを表す RGBA 色と、アルファ ブレンディング係数 (RGBA 色のアルファ成分) として指定する。マテリアルのスペキュラ属性は、色および強度で指定する。詳細については、「ライティングとマテリアルのカラー値」を参照すること。

ディフューズ反射とアンビエント反射

D3DMATERIAL8 型の diffuse および ambient メンバは、シーン内でマテリアルがアンビエント ライトとディフューズ ライトをどのように反射するかを指定する。ほとんどのシーンでは、アンビエント ライトよりもディフューズ ライトの方がずっと多く使用されるため、色の決定においてはディフューズ反射が最も大きく影響する。さらに、ディフューズ ライトは向きを持っているため、その入射角は反射の全体的な強度に影響を与える。ディフューズ反射は、ライトが頂点法線と平行に頂点に当るときが最も強い。入射角が大きくなるにつれて、ディフューズ反射のエフェクトは減少する。次に示すように、反射光の量は入射光と頂点法線がなす角度の余弦である。

アンビエント ライトと同様、アンビエント反射は向きを持たない。アンビエント反射は、レンダリングしたオブジェクトの見かけの色への影響は少ないが、全体の色に影響し、マテリアルから反射するディフューズ ライトがまったくないか、ほんのわずかであるときに最も目立つ。マテリアルのアンビエント反射は、D3DRS_AMBIENT フラグを指定して Direct3DDevice8.SetRenderState メソッドを呼び出すことでシーンに設定したアンビエント ライトの影響を受ける。

ディフューズ反射およびアンビエント反射は、ともに作用してオブジェクトで知覚される色を決める。これらは通常は同じ値である。たとえば、青色の水晶オブジェクトをレンダリングするには、ディフューズ ライトとアンビエント ライトの青成分のみ反射するマテリアルを作成する。この水晶を白色光で照らされた部屋に置くと青色に見える。しかし、赤色光しかない部屋では、同じ水晶でも黒く見える。これは、水晶のマテリアルが赤色光を反射しないためである。

エミッション

マテリアルを使用して、レンダリングしたオブジェクト自体が光を発しているように見せることができる。D3DMATERIAL8 型の emissive メンバを使用して、エミッション光の色と透明度を指定する。エミッションはオブジェクトの色に影響する。たとえば、暗いマテリアルを明るくし、発光色の一部になることができる。

マテリアルのエミッション属性を使用して、オブジェクトが光を発しているように見せることができる。この方法では、シーンにライトを追加する際のオーバーヘッドが発生しない。青色の水晶の例で、シーン内のほかのオブジェクトにはライトを照らさずに、水晶だけが輝いているように見せる場合は、エミッション属性を使用するとよい。エミッション属性を持つマテリアルが発する光は、シーン内のほかのオブジェクトで反射できる光ではないので注意すること。この反射光を得るには、シーン内に追加のライトを配置する必要がある。

スペキュラ反射

スペキュラ反射はオブジェクト上にハイライトを作成し、オブジェクトが輝いているように見せる。D3DMATERIAL8 型には、スペキュラ ハイライト色とマテリアルの全体的な輝きを指定する 2 つのメンバが含まれる。specular メンバを目的の RGBA 色 (最も一般的な色は白色または明るいグレーである) に設定して、スペキュラ ハイライトの色を決める。power メンバに設定する値は、スペキュラ エフェクトのシャープさを制御する。

スペキュラ ハイライトを使用すると、すばらしいエフェクトが得られる。再び青色の水晶を例として考える。power の値が大きいほど鮮明なスペキュラ ハイライトになり、水晶の輝きが増す。この値が小さいほどエフェクトの及ぶ領域は拡大するが、反射が鈍くなり水晶が霜で覆われたように見える。まったく光沢のないオブジェクトにするには、power メンバをゼロに設定し、specular の色を黒に設定する。思いどおりのリアルな表示になるように、さまざまな反射レベルを試してみる。次の図は、2 つの同じモデルを示している。左側のモデルではスペキュラ反射強度を 10 に設定し、右側のモデルではスペキュラ反射を設定していない。


マテリアルの使い方

ここでは、Microsoft® Direct3D® アプリケーションでのマテリアルの使用方法について説明する。説明するトピックは、次のとおりである。

  • マテリアル プロパティの設定
  • マテリアル プロパティの取得


マテリアル プロパティの設定

Microsoft® Direct3D® レンダリング デバイスでは、一度に 1 つのマテリアル プロパティのセットでレンダリングできる。

Microsoft® Visual Basic® アプリケーションの場合、システムで使用するマテリアル プロパティを設定するには、D3DMATERIAL8 型を用意し、次に Direct3DDevice8.SetMaterial メソッドを呼び出す。

D3DMATERIAL8 型を用意するには、この型にプロパティ情報を設定して、レンダリングでの目的のエフェクトを作成する。次のコードは、シャープな白色のスペキュラ ハイライトがある、紫色のマテリアル用の D3DMATERIAL8 型を設定する。

Dim mat As D3DMATERIAL8

' ディフューズ反射を表す RGBA を設定する。
mat.diffuse.r = 0.5
mat.diffuse.g = 0#
mat.diffuse.b = 0.5
mat.diffuse.a = 1#

' アンビエント反射を表す RGBA を設定する。
mat.ambient.r = 0.5
mat.ambient.g = 0#
mat.ambient.b = 0.5
mat.ambient.a = 1#

' スペキュラ ハイライトの色とシャープさを設定する。
mat.specular.r = 1#
mat.specular.g = 1#
mat.specular.b = 1#
mat.specular.a = 1#
mat.power = 50#

' RGBA エミッション色を設定する。
mat.Emissive.r = 0#
mat.Emissive.g = 0#
mat.Emissive.b = 0#
mat.Emissive.a = 0#

D3DMATERIAL8 型を用意したら、レンダリング デバイスの Direct3DDevice8.SetMaterial メソッドを呼び出してこの構造体を適用する。このメソッドには、用意した D3DMATERIAL8 型のアドレスを唯一のパラメータとして指定する。デバイスのマテリアル プロパティの更新が必要なときは、新しい情報で SetMaterial を呼び出すことができる。以上の処理を次のサンプル コードに示す。

' このコードでは、このトピックの前の例で変数 mat に対して定義した
' マテリアル プロパティを使用する。d3dDevice には
' Direct3DDevice8 への有効な参照が格納されていると仮定している。

On Local Error Resume Next

Call d3dDevice.SetMaterial(mat)
If Err.Number <> D3D_OK Then
    ' エラー処理コード。
End If

Direct3D デバイスを作成する場合は、以下の表に示すように現在のマテリアルは自動的にデフォルトに設定される。

メンバ | 値
Diffuse | (R:1, G:1, B:1, A:0)
Specular | (R:0, G:0, B:0, A:0)
Ambient | (R:0, G:0, B:0, A:0)
Emissive | (R:0, G:0, B:0, A:0)
Power | (0.0)


マテリアル プロパティの取得

デバイスに対して Direct3DDevice8.GetMaterial メソッドを呼び出して、レンダリング デバイスで現在使用しているマテリアル プロパティを取得する。Direct3DDevice8.SetMaterial メソッドの場合とは異なり、GetMaterial では準備は必要ない。GetMaterial メソッドには、D3DMATERIAL8型の変数を指定する。このメソッドは、終了前にこの変数に現在のマテリアル プロパティの情報を書き込む。

' この例では、変数 d3dDevice には Direct3DDevice8 オブジェクトへの
' 有効な参照が格納されていると仮定する。
On Local Error Resume Next
Dim mat As D3DMATERIAL8

Call d3dDevice.GetMaterial(mat)
If Err.Number <> D3D_OK Then
    ' エラー処理コード。
End If


頂点フォーマット

ここでは、Microsoft® Direct3D® で頂点を指定するために理解しておく必要がある概念について説明し、頂点を宣言するためにアプリケーションで使用できる各種フォーマットの情報について説明する。説明するトピックは、次のとおりである。

  • 頂点フォーマットについて
  • 未トランスフォーム 未ライティングの頂点
  • 未トランスフォーム ライティング済みの頂点
  • トランスフォーム済み ライティング済みの頂点
  • トランスフォーム済み ライティング済みの頂点の機能
  • 柔軟な頂点フォーマットと頂点シェーダ


頂点フォーマットについて

柔軟な頂点フォーマット (FVF) のコードは、インターリーブされて格納される頂点の内容を単一データ ストリームに記述する。一般に、固定機能頂点処理パイプラインで処理されるデータを指定する。

Microsoft® Direct3D® アプリケーションでは、複数の方法でモデルの頂点を定義できる。柔軟な頂点定義 ("柔軟な頂点フォーマット" または "柔軟な頂点フォーマット コード" とも呼ぶ) がサポートされていることから、必要な頂点の成分のみアプリケーションで使用し、使用しない頂点の成分は削除できる。必要な頂点の成分のみ使用できるので、アプリケーションでメモリを節約でき、モデルのレンダリングに必要な処理帯域幅を最小限に抑えることができる。柔軟な頂点フォーマット フラグを組み合わせて使用して、頂点のフォーマット方法を指定する。

FVF 仕様にはポイント サイズのフォーマットも含まれ、D3DFVF_PSIZE によって指定する。このサイズは、非 TL 頂点についてはカメラ空間単位で、TL 頂点についてはデバイス空間単位で表される。

Microsoft® Visual Basic® の Direct3DDevice8 クラスには、これらのフラグを組み合わせを受け取るメソッドがあり、この組み合わせを使用してプリミティブのレンダリング方法を決める。基本的には、これらのフラグは、アプリケーションでどの頂点の成分 (位置座標、頂点ブレンディング ウェイト、法線、色、およびテクスチャ座標の数とフォーマット) を使用するかをシステムに知らせ、また、Direct3D でレンダリング パイプラインのどの部分を頂点の成分に適用するかを間接的に知らせる。さらに、特定の頂点フォーマット フラグの有無によって、メモリに存在する頂点の成分フィールドと、省略した頂点の成分をシステムに知らせる。

デバイスの制限を調べるには、D3DFVFCAPS_DONOTSTRIPELEMENTS および D3DFVFCAPS_TEXCOORDCOUNTMASK 柔軟な頂点フォーマット フラグについてデバイスを問い合わせる。詳細については、D3DCAPS8 型の「FVFCaps メンバ」を参照すること。

頂点のフォーマット方法に関するシステム条件の中で重要なのは、データの表示順序である。次の図は、メモリ内のすべての頂点の成分の順序とそれに関係するデータ型を示している。

テクスチャ座標はさまざまなフォーマットで宣言でき、最少 1 要素の座標、最大 4 要素のテクスチャ座標 (2D 射影テクスチャ座標の場合) を使用してテクスチャを処理できる。Math.bas からヘルパー関数の D3DFVF_TEXCOORDSIZEn セットを使用して、頂点フォーマットで使用するテクスチャ座標フォーマットを識別するためのビット パターンを作成する。Math.bas の Visual Basic コード モジュールが、この SDK に付属している。

アプリケーションがすべての単一コンポーネントを使用するとは限らない。RHW (同次 W の逆数) と頂点法線フィールドは互いに排他的である。また、ほとんどのアプリケーションで 8 つのテクスチャ座標セットをすべて使用するとも限らない。しかし、Direct3D にはこのような柔軟性がある。あるフラグを別のフラグと併用する場合には、いくつかの制限がある。これらの制限はほとんど常識で判断できる。たとえば、D3DFVF_XYZ フラグと D3DFVF_XYZRHW フラグは併用できない。この場合、未トランスフォームの頂点とトランスフォーム済みの頂点の両方を使用して、1 つの頂点の位置座標を定義することになるからである。詳細については、「柔軟な頂点フォーマット フラグ」のそれぞれの説明を参照すること。

インデックス頂点ブレンディングを使用するには、D3DFVF_LASTBETA_UBYTE4 フラグは FVF の最後に置く必要がある。このフラグを指定すると、5 番目のブレンディング ウェイトは、フロートではなく DWORD として処理される。詳細については、「インデックス付き頂点ブレンディング」を参照すること。

次のコードは、D3DFVF_LASTBETA_UBYTE4 フラグを使用する FVF コードと、このフラグを使用しない FVF コードとの違いを示している。次に定義する FVF は、D3DFVF_LASTBETA_UBYTE4 フラグを使用していない。4 つのブレンディング インデックスを使用する場合は、フラグ D3DFVF_XYZ3 が存在する。これは、4 番目のブレンディング インデックスに対して、常に (1 - 最初の 3 つの合計) を使用するからである。

Const D3DFVF_BLENDVERTEX = (D3DFVF_XYZB3 Or D3DFVF_NORMAL Or D3DFVF_TEX1)

Private Type BLENDVERTEX
    v As D3DXVECTOR  ' 頂点シェーダで v0 として参照される。
    blend1 As Single ' 頂点シェーダで v1.x として参照される。
    blend2 As Single ' 頂点シェーダで v1.y として参照される。
    blend3 As Single ' 頂点シェーダで v1.z として参照される。
                     ' v1.w = 1.0 - (v1.x + v1.y + v1.z)
    n As D3DXVECTOR  ' 頂点シェーダで v3 として参照される。
    tu as Single     ' tu および tv。頂点シェーダで v7 として参照される。
    tv As Single     '
End Type

次に定義する FVF は、D3DFVF_LAST_UBYTE4 フラグを使用している。

Const D3DFVF_BLENDVERTEX = (D3DFVF_XYZB4 Or D3DFVF_LASTBETA_UBYTE4 Or _
                            D3DFVF_NORMAL Or D3DFVF_TEX1)
Private Type BLENDVERTEX
    v As D3DXVECTOR    ' 頂点シェーダで v0 として参照される。
    blend1 As Single   ' 頂点シェーダで v1.x として参照される。
    blend2 As Single   ' 頂点シェーダで v1.y として参照される。
    blend3 As Single   ' 頂点シェーダで v1.z として参照される。
                       ' v1.w = 1.0 - (v1.x + v1.y + v1.z)
    indices As Long    ' 頂点シェーダで v2.xyzw として参照される。
    n As D3DXVECTOR    ' 頂点シェーダで v3 として参照される。
    tu As Single       ' tu および tv。頂点シェーダで v7 として参照される。
    tv As Single
End Type

詳細については、「柔軟な頂点フォーマット フラグ」を参照すること。


未トランスフォーム 未ライティングの頂点

レンダリング メソッドに渡す頂点記述に D3DFVF_XYZ または D3DFVF_XYZBn フラグのいくつか、および D3DFVF_NORMAL フラグがある場合は、「未トランスフォーム 未ライティングの頂点」タイプとして識別される。「未トランスフォーム 未ライティングの頂点」を使用すると、アプリケーションは Microsoft® Direct3D にその内部アルゴリズムを使用してすべてのトランスフォーム & ライティング処理を実行するよう効率的に要求できるD3DRS_LIGHTING レンダリング ステートを FALSE に設定して、レンダリングするプリミティブに対して Direct3D ライティング エンジンを無効にできる。

この頂点タイプは、アプリケーションで独自のトランスフォーム & ライティング エンジンを実装する必要がないので、ほとんどのアプリケーションで使用される。ただし、システムによって自動的に計算が実行されるため、各頂点に対していくらかの情報を指定しておく必要がある。

  • 未トランスフォームのモデル座標に頂点を指定することが求められる。次に、システムは、ワールド トランスフォーム、ビュー トランスフォーム、および射影トランスフォームをモデル座標に適用してシーン内に頂点を配置し、頂点の画面上での最終位置座標を決定する。
  • よりリアルなライティング エフェクトを出すために、頂点法線を含めることができる。頂点法線を含んでいない頂点をライティングで照らす場合、その頂点は 0 の内積を使用する。つまり、これらの頂点は入射光を受けないものとして処理される。システムは、カレント マテリアルに加えて、頂点法線を使用してライティング計算を実行する。詳細については、「面法線ベクトルと頂点法線ベクトル」、「ライト」、「マテリアル」、および「Direct3D のライティングにおける数学的計算」を参照すること。

これらの条件以外では、その他の頂点の成分を柔軟に使用または無視できる。たとえば、ディフューズ色またはスペキュラ色を未トランスフォームの頂点に含めることができる。これは Microsoft DirectX® 6.0 以前ではできなかった。各頂点に個々の色を含めると、マテリアル カラーのみ使用したライティング計算を実行するよりも、繊細で柔軟なシェーディング エフェクトが得られる。ただしこの場合、D3DRS_COLORVERTEX レンダリング ステートを使用して個々の頂点単位のカラーを有効にする必要がある。また、未トランスフォーム 未ライティングの頂点には、最大 8 つまでテクスチャ座標セットを含めることができる。Microsoft Visual Basic® アプリケーションでは、頂点に D3DVERTEX 型または D3DVERTEX2 型を使用できる。

これらの型がアプリケーションの要件に合わないときは、独自に定義ができる。ただし、どの頂点の成分がアプリケーションで必要であるかに注意し、必ず正しく順序付けた構造体を宣言して、必要な順序で頂点の成分が表示されるようにしなければならない。次のサンプル コードは、位置座標、頂点法線、ディフューズ色、および 2 つのテクスチャ座標セットを含む有効な頂点フォーマット構造体を宣言する。

'
' この頂点の頂点フォーマット記述は、
' (D3DFVF_XYZ Or D3DFVF_NORMAL Or D3DFVF_DIFFUSE Or D3DFVF_TEX2) になる。
'
Type UNLITVERTEX
    x As Single      ' 位置座標
    y As Single
    z As Single
    nx As Single     ' 法線
    ny As Single
    nz As Single
    Diffuse As Long  ' ディフューズ色
    tu1 As Single    ' テクスチャ座標
    tv1 As Single
    tu2 As Single    ' テクスチャ座標
    tv2 As Single
End Type

この構造体の頂点記述は、柔軟な頂点フォーマット フラグ D3DFVF_XYZ、D3DFVF_NORMAL、D3DFVF_DIFFUSE、および D3DFVF_TEX2 の組み合わせになる。

詳細については、「頂点フォーマットについて」を参照すること。


未トランスフォーム ライティング済みの頂点

Microsoft® Direct3D® レンダリング メソッドで使用する頂点フォーマット記述に D3DFVF_XYZ フラグを含め、D3DFVF_NORMAL フラグを含めていない場合、その頂点は「未トランスフォーム ライティング済みの頂点」として識別される。フラグの依存および排他関係の詳細については、「柔軟な頂点フォーマット フラグ」を参照すること。

「未トランスフォーム ライティング済みの頂点」を使用すると、アプリケーションは Direct3D に頂点に対するライティング計算を実行しないように要求するが、Direct3D は以前に設定されたワールド行列、ビュー行列、および射影行列を使用して頂点をトランスフォームする。ライティング計算は実行されないので、頂点法線は必要ない。システムは、各頂点のディフューズ成分とスペキュラ成分をシェーディングに使用する。これらの色は任意に指定しても、独自のライティング公式を使用して計算してもよい。ディフューズ成分またはスペキュラ成分を含めない場合は、デフォルト カラーが使用される。ディフューズ色のデフォルト値は 0xFFFFFFFF で、スペキュラ色のデフォルト値は 0x0 である。

位置座標といくらかの色情報を含めるという点を除いては、その他の頂点タイプと同様、未ライティングの頂点フォーマットにテクスチャ座標セットを含めたり、無視することができる。

Microsoft Visual Basic® で記述されたアプリケーションでは、独自の頂点フォーマットを定義しても、ライティングのある頂点に D3DLVERTEX 型または D3DLVERTEX2 型を使用してもよい。これらの型にアプリケーションで必要なすべてのフィールドが含まれていない場合は、別の型を定義することができる。新しい構造体を宣言するときは、必ず頂点の成分が正しい順序になるようにする。次のサンプル コードは、ディフューズ頂点カラー、スペキュラ頂点カラー、および 3 つのテクスチャ座標セットを持つ、未トランスフォームでライティング済みの有効な頂点を宣言する。

'
' この頂点の頂点フォーマット記述は、
' (D3DFVF_XYZ Or D3DFVF_DIFFUSE Or
'    D3DFVF_SPECULAR Or D3DFVF_TEX3)
' になる。
'
Type LITVERTEX
    x As Single      ' 位置座標
    y As Single
    z As Single
    Diffuse As Long  ' ディフューズ色
    Specular As Long ' スペキュラ色
    tu1 As Single ' テクスチャ座標
    tv1 As Single
    tu2 As Single
    tv2 As Single
    tu3 As Single
    tv3 As Single
End Type

この型での頂点記述は、柔軟な頂点フォーマット フラグ D3DFVF_XYZ、D3DFVF_DIFFUSE、D3DFVF_SPECULAR、および D3DFVF_TEX3 の組み合わせになる。

詳細については、「頂点フォーマットについて」を参照すること。


トランスフォーム済み ライティング済みの頂点

頂点フォーマット記述に D3DFVF_XYZRHW フラグを含めた場合、アプリケーションで「トランスフォーム済み ライティング済みの頂点」を使用することがシステムに通知される。これは、Microsoft® Direct3D® でワールド行列、ビュー行列、または射影行列を使用して頂点をトランスフォームせず、ライティング計算も実行しないことを意味している。つまり、Direct3D は、アプリケーションでこれらの処理が実行済みであると見なしている。これにより、既存の 3D アプリケーションを Direct3D に移植するとき、トランスフォーム済み ライティング済みの頂点がそのまま使える。要するに、Direct3D は、「トランスフォーム済み ライティング済みの頂点」をまったく変更しない。ドライバに直接渡してラスタ化を実行する。

未トランスフォームの頂点とライティングに関連付けられている頂点フォーマット フラグ (D3DFVF_XYZ と D3DFVF_NORMAL) は、D3DFVF_XYZRHW がある場合は使用できない。フラグの依存および排他関係の詳細については、「柔軟な頂点フォーマット フラグ」を参照すること。

頂点位置座標を指定するときは、トランスフォーム済みのものを指定しなければならない。x と y の値はスクリーン座標内に存在している必要があり、z は Z バッファで使用されるピクセルの深度値でなければならない。z 値は 0.0 ～ 1.0 の値である。0.0 はユーザーに最も近い位置座標で、1.0 は可視領域内の最も遠い位置座標である。「トランスフォーム済み ライティング済みの頂点」は、位置座標のすぐ後に RHW 値 (同次 W の逆数) を含んでいなければならない。RHW は、射影空間内で頂点が存在する同次ポイント (x、y、z、w) からの W 座標の逆数である。この値は、z 軸に沿った、視点から頂点までの距離になることが多い。

位置座標と RHW の条件を除けば、この頂点フォーマットは、「未トランスフォーム ライティング済みの頂点」と同じである。これまでの説明を以下にまとめる。

  • このフォーマットの場合、ライティング計算は実行されないので、頂点法線は必要ない。
  • ディフューズ色またはスペキュラ色を指定できる。これを指定しない場合は、0x0 がスペキュラ色に、0xFFFFFFFF がディフューズ色に使用される。
  • テクスチャ座標セットは、最大 8 つまで使用できる。また、使用しなくてもよい。

Microsoft Visual Basic® アプリケーションでは、「トランスフォーム済み ライティング済みの頂点」に対して D3DTLVERTEX 型または D3DTLVERTEX2 型を使用できる。これらの型にアプリケーションで必要なすべてのフィールドが含まれていない場合は、別の型を定義することができる。新しい構造体を宣言するときは、必ず頂点の成分が正しい順序になるようにする。次のサンプル コードは、ディフューズ頂点カラー、スペキュラ頂点カラー、およびテクスチャ座標セットを 1 つだけ持つ、トランスフォーム済みでライティングのある有効な頂点を宣言する。

'
' この頂点の頂点フォーマット記述は、
' (D3DFVF_XYZRHW Or D3DFVF_DIFFUSE Or D3DFVF_SPECULAR Or D3DFVF_TEX1) になる。
'
Type TRANSLITVERTEX
    x As Single       ' スクリーン座標
    y As Single
    z As Single       ' Z バッファ深度
    rhw As Single     ' 同次 W の逆数
    Diffuse As Long   ' ディフューズ色
    Specular As Long  ' スペキュラ色
    tu1 As Single     ' テクスチャ座標
    tv1 As Single
End Type

この型の頂点記述は、柔軟な頂点フォーマット フラグ D3DFVF_XYZRHW、D3DFVF_DIFFUSE、D3DFVF_SPECULAR、および D3DFVF_TEX1 の組み合わせになる。

詳細については、「頂点フォーマットについて」および「トランスフォーム済み ライティング済みの頂点の機能」を参照すること。


トランスフォーム済み ライティング済みの頂点の機能

柔軟な頂点フォーマット (FVF) コードで指定された頂点データは、トランスフォーム済みまたは未トランスフォームのいずれかのプロパティを持つ。FVF 指定のトランスフォーム済み頂点は、TL (transformed and lit) 頂点と呼ばれる。Microsoft® Direct3D® for Microsoft DirectX® 8.0 では、前リリースと同様、TL 頂点データがサポートされている。しかし、TL 頂点は、未トランスフォームの頂点には適用されないいくつかの条件に影響される。

TL 頂点データは、FVF コードで指定された頂点に対してのみ有効であり、プログラム可能な頂点シェーダの入力としては使用できない。プログラム可能な頂点シェーダは、各種フォームのトランスフォーム済み頂点データを使用できる柔軟性があるが、変換はシェーダの一部であって頂点データのプロパティではないため、FVF の TL 頂点データとは異なっている。TL 頂点データは、FVF コードによって定義されているため、継承的に単一ストリームでもある。

TL 頂点データが Direct3D でクリッピングされるかどうかは保証がないため、TL 頂点プリミティブを Direct3D に送ってレンダリングするには、事前にクリッピングする必要がある。x 値と y 値は、ビューポートに対して、またはデバイス ガードバンドがあればそれに対して、クリッピングする必要がある。TL 頂点の z 値は、0 と 1 の間でなければならない (0 と 1 を含む)。また RHW 値は、[0 < 1/D3DCAPS8.MaxVertexW] の範囲内でなければならない。RHW 要件は、w 値がハードウェア ラスタ化デバイスのサポート範囲内に収まるようにすることである。頂点の w および RHW 範囲がパースペクティブ射影トランスフォームの結果である場合、射影行列のすべての値にスケールを適用して修正できる。

注 D3DPMISCCAPS_CLIPTLVERTS が設定されている場合、デバイスはトランスフォーム後の頂点データを z および (x, y) ビューポートの限界に対してクリッピングする。ユーザー定義のクリップ面に対するクリッピングは、トランスフォーム後の頂点データについてはサポートされていない。D3DPMISCCAPS_CLIPTLVERTS 能力が設定されていない場合、アプリケーションがこれらのプリミティブを z 境界と少なくとも x と y のガードバンドの範囲に対してクリッピングする必要がある。一方、トランスフォーム前の頂点についてのクリッピングは、続けて別の描画呼び出しが行われるような、転送先頂点バッファに対する描画呼び出しと頂点処理呼び出しの両方で十分にサポートされている。このサポートには、z と (x, y) ビューポート限界に加えてユーザー定義のクリップ面も含まれる。

TL 頂点データは、常に、ドライバに直接渡されてレンダリングされる。TL 頂点データを持つ頂点バッファを使用すると、ドライバがこれらの頂点バッファを AGP またはビデオ メモリに割り当てる処理速度がかなり向上する。TL 頂点バッファの割り当ては、非 TL 頂点データ (FVF または非 FVF のいずれか) がドライバによって割り当てられない場合でも、ドライバによって割り当てることができる。これは、トランスフォームおよびライティングをサポートしないハードウェア デバイス上で動作する場合と同様である。

詳細については、「トランスフォーム済み ライティング済みの頂点」を参照すること。


柔軟な頂点フォーマットと頂点シェーダ

Microsoft® Direct3D® for Microsoft DirectX® 8.0 は、単一入力ストリームの固定機能頂点処理パイプラインを使用するためのプログラミング モデルを簡素化し、これまでの DirectX リリースと同様の機能を提供する。この場合、頂点シェーダは、現在の頂点シェーダを設定するときに頂点シェーダ ハンドルの代わりとして渡された柔軟な頂点フォーマット (FVF) コードから成る。頂点シェーダのハンドル空間はランタイム ライブラリによって管理され、この用途のために、有効な FVF コードのハンドルが予約されている。

FVF コードを現在の頂点シェーダとして設定すると、頂点処理はストリーム ゼロからのみロードされ、頂点要素は FVF コードの定義に従って変換される。

次のサンプル コードは、Microsoft Visual Basic® アプリケーションにおける FVF コードの頂点シェーダとしての使用方法を示している。

まず最初に、カスタム頂点タイプの構造体を定義し、頂点を初期化する。この例では、三角形をレンダリングするため、3 つの頂点が初期化される。

' このコードで、d3dDevice は、Direct3DDevice8 オブジェクトへの
' 有効な参照であると仮定している。

Private Type CUSTOMVERTEX
    x As Single         ' スクリーン空間 x 座標。
    y As Single         ' スクリーン空間 y 座標。
    z  As Single        ' 正規化された z 座標。
    rhw As Single       ' 正規化された z rhw 座標。
    color As Long       ' 頂点カラー。
End Type

Const D3DFVF_CUSTOMVERTEX = (D3DFVF_XYZRHW Or D3DFVF_DIFFUSE)

Dim Vertices(2) As CUSTOMVERTEX
Dim VertexSizeInBytes As Long

VertexSizeInBytes = Len(Vertices(0))

With Vertices(0): .x = 150: .y =  50: .z = 0.5: .rhw = 1: .color = &HFFFF0000: End With
With Vertices(1): .x = 250: .y = 250: .z = 0.5: .rhw = 1: .color = &HFF00FF00: End With
With Vertices(2): .x =  50: .y = 250: .z = 0.5: .rhw = 1: .color = &HFF00FFFF: End With

次に、ストリーム ゼロを使用してプリミティブをレンダリングする。

sizeOfVertex = Len(v)
d3dDevice.SetStreamSource 0, g_VB, sizeOfVertex
d3dDevice.SetVertexShader D3DFVF_CUSTOMVERTEX
d3dDevice.DrawPrimitive D3DPT_TRIANGLELIST, 0, 1

詳細については、「頂点シェーダ」を参照すること。


テクスチャ

テクスチャは、コンピュータでリアルな 3D 画像を生成するための強力なツールである。Microsoft® Direct3D® では、多彩なテクスチャ機能をサポートしており、高度なテクスチャ技術を簡単に利用できる。ここでは、Direct3D でのテクスチャの用途とその使用方法について説明する。説明するトピックは、次のとおりである。

  • 基本的なテクスチャ処理の概念
  • テクスチャ座標
  • テクスチャ リソース
  • テクスチャ フィルタリング
  • テクスチャ ラッピング
  • テクスチャ ブレンディング
  • 圧縮したテクスチャ リソース
  • ボリューム テクスチャ リソース
  • 自動テクスチャ管理
  • テクスチャ処理におけるハードウェアによる制約


基本的なテクスチャ処理の概念

ここでは、Microsoft® Direct3D® でのテクスチャ処理の理解に必要な最も基本的な概念について説明する。説明するトピックは、次のとおりである。

  • テクスチャとは
  • テクスチャ アドレッシング モード
  • テクスチャのダーティー領域
  • テクスチャ パレット


テクスチャとは

これまではコンピュータで生成する 3D 画像は、当時としては一般に高度なものではあったが、プラスチックが光っているように見える傾向があった。当時の 3D 画像には、傷、ひび、指紋、汚れなどを 3D オブジェクトでリアルに表現する方法がなかった。近年、開発者の間では、コンピュータでよりリアルな 3D 画像を生成するためのツールとして、テクスチャが広く使用されるようになっている。

テクスチャという用語は、普通、オブジェクトの滑らかさや粗さをいう。しかし、コンピュータ グラフィックス分野におけるテクスチャとは、オブジェクトをテクスチャのように見せるピクセル カラーのビットマップのことである。

Microsoft® Direct3D® のテクスチャはビットマップであるため、ビットマップでさえあれば Direct3D プリミティブに適用できる。たとえば、アプリケーションでは、木目模様に見えるオブジェクトを作成して操作することができる。丘を形成する 3D プリミティブ セットに、芝生、土、岩を適用できる。その結果、本物のような丘の斜面ができあがる。テクスチャ処理では、また、道路脇の標識、崖の岩層などのエフェクトを作成したり、大理石の床を作成することもできる。

さらに、Direct3D は、テクスチャ ブレンディング (透明度あり/なし) やライト マッピングなど、より高度なテクスチャ技法もサポートしている。詳細については、「テクスチャ ブレンディング」および「テクスチャによるライト マッピング」を参照すること。

アプリケーションで、ハードウェア アブストラクション レイヤ (HAL) デバイス、またはソフトウェア デバイス (「デバイスの種類」を参照すること) を作成する場合は、8 ビット、16 ビット、24 ビット、または 32 ビットのテクスチャを使用できる。


テクスチャ アドレッシング モード

ここでは、Microsoft® Direct3D® テクスチャ アドレッシング モードの用途およびその使用方法について説明する。説明するトピックは、次のとおりである。

  • テクスチャ アドレッシング モードとは
  • ラップ テクスチャ アドレッシング モード
  • ミラー テクスチャ アドレッシング モード
  • クランプ テクスチャ アドレッシング モード
  • 境界色テクスチャ アドレッシング モード
  • テクスチャ アドレッシング モードの設定と取得
  • テクスチャ アドレッシング モードとテクスチャ ラッピング
  • テクスチャ アドレッシングにおけるデバイス制限


テクスチャ アドレッシング モードとは

Microsoft® Direct3D® アプリケーションでは、どのプリミティブのどの頂点にもテクスチャ座標を割り当てることができる。詳細については、「テクスチャ座標」を参照すること。通常、頂点に割り当てるテクスチャ座標 u および v の範囲は、0.0 と 1.0 を含む 0.0 ～ 1.0 である。しかし、この範囲外のテクスチャ座標を割り当てて、特殊なテクスチャ エフェクトを作成することもできる。

テクスチャ アドレッシング モードを設定することで、[0.0, 1.0] の範囲外のテクスチャ座標で Direct3D が行う処理を制御できる。たとえば、アプリケーションでテクスチャ アドレッシング モードを設定して、プリミティブ全体にテクスチャをタイルのように張ることができる。次のトピックでさらに詳しく説明する。

  • ラップ テクスチャ アドレッシング モード
  • ミラー テクスチャ アドレッシング モード
  • クランプ テクスチャ アドレッシング モード
  • 境界色テクスチャ アドレッシング モード


ラップ テクスチャ アドレッシング モード

CONST_D3DTEXTUREADDRESS 列挙の D3DTADDRESS_WRAP メンバで指定するラップ テクスチャ アドレッシング モードでは、Microsoft® Direct3D® はすべての整数接合でテクスチャを繰り返し適用する。たとえば、アプリケーションで正方形プリミティブを作成し、テクスチャ座標 (0.0,0.0)、(0.0,3.0)、(3.0,3.0)、および (3.0,0.0) を指定する場合を考える。テクスチャ アドレッシング モードを D3DTADDRESS_WRAP に設定すると、u および v の両方向でテクスチャが 3 回適用される。

次の図にこれを示す。

このテクスチャ アドレッシング モードのエフェクトは、ミラー モードのエフェクトに類似する部分がある。詳細については、「ミラー テクスチャ アドレッシング モード」を参照すること。


ミラー テクスチャ アドレッシング モード

CONST_D3DTEXTUREADDRESS 列挙の D3DTADDRESS_MIRROR メンバで指定するミラー テクスチャ アドレッシング モードでは、Microsoft® Direct3D® はすべての整数境界でテクスチャをミラーリングする。たとえば、アプリケーションで正方形プリミティブを作成し、テクスチャ座標 (0.0,0.0)、(0.0,3.0)、(3.0,3.0)、および (3.0,0.0) を指定する場合を考える。テクスチャ アドレッシング モードを D3DTADDRESS_MIRROR に設定すると、u および v の両方向でテクスチャが 3 回適用される。テクスチャが適用されるその他のすべての行と列は、直前の行または列の鏡像になる。

次の図にこれを示す。

このテクスチャ アドレッシング モードのエフェクトは、ラップ モードのエフェクトに類似する部分がある。詳細については、「ラップ テクスチャ アドレッシング モード」を参照すること。


クランプ テクスチャ アドレッシング モード

CONST_D3DTEXTUREADDRESS 列挙の D3DTADDRESS_CLAMP メンバで指定するクランプ テクスチャ アドレッシング モードでは、Microsoft® Direct3D® はテクスチャ座標を [0.0, 1.0] の範囲に制限する。つまり、テクスチャを 1 回適用し、次に、エッジのピクセルの色を塗り付けていく。たとえば、アプリケーションで正方形プリミティブを作成し、テクスチャ座標 (0.0,0.0)、(0.0,3.0)、(3.0,3.0)、および (3.0,0.0) をそのプリミティブの頂点に割り当てる場合を考える。テクスチャ アドレッシング モードを D3DTADDRESS_CLAMP に設定すると、テクスチャが 1 回適用される。最初の列と最後の行のピクセル カラーが、プリミティブの上と右にそれぞれ広がっていく。

次の図にこれを示す。


境界色テクスチャ アドレッシング モード

CONST_D3DTEXTUREADDRESS 列挙の D3DTADDRESS_BORDER メンバで指定する境界色テクスチャ アドレッシング モードでは、Microsoft® Direct3D® は 0.0 と 1.0 を含む 0.0 ～ 1.0 の範囲外のすべてのテクスチャ座標に対して、境界色と呼ばれる任意の色を使用する。

次の図は、この処理を示している。この図では、アプリケーションは赤色の境界色を使用してテクスチャをプリミティブに適用するように指定している。

Microsoft Visual Basic® アプリケーションでは、Direct3DDevice8.SetTextureStageState を呼び出して境界色を設定する。これを呼び出すときの第 1 パラメータには目的のテクスチャ ステージ識別子を設定し、第 2 パラメータには D3DTSS_BORDERCOLOR ステージ ステート値を設定し、第 3 パラメータには新しい RGBA 境界色を設定する。


テクスチャ アドレッシング モードの設定と取得

Direct3DDevice8.SetTextureStageState メソッドを呼び出して、各テクスチャ ステージにテクスチャ アドレッシング モードを設定できる。第 1 パラメータに目的のテクスチャ ステージ識別子を指定する。第 2 パラメータに D3DTSS_ADDRESSU、D3DTSS_ADDRESSV、または D3DTSS_ADDRESSW 値を設定して、u、v、または w アドレッシング モードを個別に更新する。SetTextureStageState に渡す第 3 パラメータは、設定されているモードを判別する。これには、CONST_D3DTEXTUREADDRESS 列挙のいずれのメンバを指定してもかまわない。

テクスチャ ステージの現在のテクスチャ アドレッシング モードを取得するには、Direct3DDevice8.GetTextureStageState を呼び出し、CONST_D3DTEXTURESTAGESTATETYPE 列挙の D3DTSS_ADDRESSU、D3DTSS_ADDRESSV、または D3DTSS_ADDRESSW メンバを使用して、情報の取得対象のアドレッシング モードを識別する。


テクスチャ アドレッシング モードとテクスチャ ラッピング

Direct3D を使用して、アプリケーションではテクスチャ ラッピングを実行できる。テクスチャ アドレッシング モードを D3DTADDRESS_WRAP に設定することと、テクスチャ ラッピングを実行することとは同じではないことに注意すること。テクスチャ アドレッシング モードを D3DTADDRESS_WRAP に設定すると、現在のプリミティブに適用される転送元テクスチャのコピーが複数生成される。テクスチャ ラッピングを有効にすると、テクスチャ処理されたポリゴンをシステムがラスタ処理する際の方法が変更される。詳細については、「テクスチャ ラッピング」を参照すること。

テクスチャ ラッピングを効果的に有効にすると、[0.0, 1.0] 外にあるテクスチャ座標を無効にでき、このような不適切なテクスチャ座標のラスタ化の動作を未定義にできる。テクスチャ ラッピングが有効になっていると、テクスチャ アドレッシング モードは使用されない。テクスチャ ラッピングが有効になっている場合には、アプリケーションで指定するテクスチャ座標が0.0 より小さく、または 1.0 より大きくならないように注意すること。


テクスチャ アドレッシングにおけるデバイス制限

一般に、システムでは 0.0 ～ 1.0 (0.0 と 1.0 を含む) の範囲外にあるテクスチャ座標でも使用できるが、多くの場合、その許容範囲はハードウェア制限によって影響される。デバイス能力を取得すると、レンダリング デバイスはこの制限を D3DCAPS8 型の MaxTextureRepeat メンバに知らせる。このメンバ内の値は、デバイスで使用可能なテクスチャ座標の全範囲を示す。たとえば、この値が 128 の場合、入力テクスチャ座標は -128.0 ～ +128.0 の範囲内になければならない。この範囲外のテクスチャ座標を持つ頂点を渡すと無効になる。自動テクスチャ座標生成およびテクスチャ座標トランスフォームの結果として生成されたテクスチャ座標に対しても、これと同じ制限が適用される。

MaxTextureRepeat の解釈も D3DPTEXTURECAPS_TEXREPEATNOTSCALEDBYSIZE 能力ビットによって変わる。このビットを設定すると、D3DCAPS8 の MaxTextureRepeat メンバの値が定義どおりに正確に使用される。ただし、D3DPTEXTURECAPS_TEXREPEATNOTSCALEDBYSIZE が設定されていない場合は、テクスチャ反復制限は、テクスチャ座標によってインデックス化されたテクスチャのサイズに依存する。この場合、有効なテクスチャ座標の範囲を計算するために、MaxTextureRepeat は、現在のテクスチャ サイズによって最大詳細レベルでスケーリングされる必要がある。たとえば、テクスチャの寸法が 32 で、MaxTextureRepeat 値が 512 の場合、実際の有効なテクスチャ座標範囲は 512/32 = 16 となる。したがって、このデバイスでは -16.0 ～ +16.0 の範囲内にテクスチャ座標が存在する必要がある。


テクスチャのダーティー領域

アプリケーションでは、テクスチャ上にダーティー領域を指定して、テクスチャのどのサブセットをコピーするかを最適化できる。ダーティー領域としてマークされた領域のみが、Direct3DDevice8.UpdateTexture 呼び出しでコピーされる。ただし、ダーティー領域はアライメントを最適化するために拡大されることがある。テクスチャ作成時には、テクスチャ全体がダーティーと見なされる。ダーティー状態のテクスチャに影響を与える処理は、以下の 4 つである。

  • テクスチャにダーティー領域を追加する。
  • テクスチャ内のバッファのいくつかをロックする。この処理では、ロックされた領域をダーティー領域として追加する。アプリケーションでは、実際のダーティー領域がよくわかっていれば、このダーティー領域の自動更新はオフにできる。
  • Direct3DDevice8.CopyRects の転送先にテクスチャを使用すると、テクスチャ全体がダーティーとしてマークされる。
  • UpdateTexture の転送元にテクスチャを使用すると、転送元テクスチャのダーティー領域がすべてクリアされる。

ダーティー領域はミップマップ テクスチャの最上位レベルに設定され、UpdateTexture は、ダーティー領域をミップ チェーンまで拡大して各サブレベルでコピーされるバイト数を最小限に抑えることができる。サブレベル ダーティー領域の座標は外側に丸められる、つまり小数部分はテクスチャに最も近接するエッジに丸められることに注意すること。

テクスチャ タイプによってダーティー領域のタイプも異なるため、テキスチャ タイプごとにメソッドがある。2D テクスチャはダーティー矩形を、ボリューム テクスチャはボックスを使用する。

  • Direct3DCubeTexture8.AddDirtyRect
  • Direct3DTexture8.AddDirtyRect
  • Direct3DVolumeTexture8.AddDirtyBox

上記メソッドの DirtyRect または DirtyBox パラメータに ByVal 0 を渡すと、ダーティー領域が拡大してテクスチャ全体を覆う。

各ロッキング メソッドは D3DLOCK_NO_DIRTY_UPDATE を取り、これによって、テクスチャのダーティー状態が変更されるのを防ぐことができる。詳細については、「リソースのロック」を参照すること。

アプリケーションは、ロック処理使用可能時に、領域のトゥルー セットに関する詳細情報が変更されたときは、D3DLOCK_NO_DIRTY_UPDATE を使用する。(最上位レベルまでロックまたはコピーしないで) テクスチャのサブレベルのみをロックまたはコピーしても、そのテクスチャのダーティー領域は更新されないことに注意すること。アプリケーションでも、最上位レベルをロックせずに下位レベルをロックしても、ダーティー領域は更新されない。


テクスチャ パレット

Microsoft® Direct3D® for DirectX® 8.0 は、Direct3DDevice8 オブジェクトに関連付けられた 256 エントリのパレット セットによるパレット テクスチャをサポートする。パレットをカレントにするには、Direct3DDevice8.SetCurrentTexturePalette メソッドを呼び出す。カレント パレットは、すべてのアクティブ テクスチャ ステージのすべてのパレット テクスチャに使用される。Direct3DDevice8.SetPaletteEntries は、パレットの 256 エントリをすべて更新する。各エントリは、フォーマット D3DFMT_A8R8G8B8 の PALLETTEENTRY 型である。すべてのエントリはデフォルトで 0xFFFFFFFF に設定される。DirectX 8 の時点では、PALLETTEENTRY 構造体の peFlags メンバは、Microsoft Platform Software Development Kit (SDK) で説明されているようには動作しないことに注意すること。peFlags メンバは今後、8 ビットのパレット化されたフォーマットのアルファ チャネルである。

Direct3DDevice8 パレットは、アルファ チャネルを含む。このアルファ チャネルは、デバイスがパレットからのアルファ チャネルをサポートすることを示す D3DPTEXTURECAPS_ALPHAPALETTE デバイス能力フラグが設定されているときに使用できる。パレット アルファ チャネルは、テクスチャ フォーマットにアルファ チャネルがない場合に使用する。デバイスがパレットからのアルファをサポートせず、テクスチャ フォーマットにアルファ チャネルがない場合は、0xFF の値がアルファに使用される。

最大で 16,384 のパレットがある。パレット セットに関連付けられるメモリ リソースは、アプリケーションが参照するパレットの最大数に比例するため、パレット番号には、ゼロから始まる連続する数を使用しなければならない。


テクスチャ座標

ここでは、テクスチャ座標の概念、テクスチャ座標フォーマット、およびテクスチャ座標フォーマットを操作する Microsoft® Direct3D® のサービスについて説明する。説明するトピックは、次のとおりである。

  • テクスチャ座標について
  • テクセルとピクセル間の直接マッピング
  • テクスチャ座標フォーマット
  • テクスチャ座標処理


テクスチャ座標について

ほとんどのテクスチャは、ビットマップ同様、カラー値の 2 次元配列である。ただし、キューブ環境マップ テクスチャは除く。詳細については、「キューブ環境マップ」を参照すること。個々のカラー値は、テクスチャ要素またはテクセルと呼ばれる。各テクセルは、テクスチャ内の一意のアドレスを持つ。このアドレスは、それぞれ u と v で表される行と列の番号であると考えることができる。

テクスチャ座標はテクスチャ空間にある。つまり、テクスチャ座標は、テクスチャ内の (0,0) を基準にした相対位置座標に存在する。テクスチャを 3D 空間のプリミティブに適用するとき、そのテクセル アドレスをオブジェクト座標にマッピングしなければならない。その後、このアドレスをスクリーン座標、つまりピクセル位置座標に平行移動する必要がある。

Microsoft® Direct3D® は、テクスチャ空間のテクセルをスクリーン空間のピクセルに直接マッピングする。これにより、中間の手順が省略され、効率が高まる。このマッピング処理は、実際は逆マッピングである。つまり、スクリーン空間の各ピクセルについて、テクスチャ空間の対応するテクセル位置座標が計算される。このポイントまたはこの周囲でテクスチャ カラーがサンプリングされる。このサンプリング処理は、テクスチャ フィルタリングと呼ばれる。詳細については、「テクスチャ フィルタリング」を参照すること。

テクスチャの各テクセルは、テクセル座標で指定できる。しかし、テクセルをプリミティブにマッピングするためには、Direct3D は、すべてのテクスチャのすべてのテクセルに対して同一のアドレス範囲を必要とする。したがって、すべてのテクセル アドレスが 0.0 ～ 1.0 の範囲にある包括的アドレス指定スキームが使用される。2D デカルト座標が x、y 座標で指定されるのと同様、Direct3D アプリケーションでは u と v の値でテクスチャ座標を指定する。実際には、0.0 ～ 1.0 の範囲外のテクスチャ座標を処理することも可能で、テクスチャ アドレッシングで設定するパラメータを使用してこの処理を行う。詳細については、「テクスチャ アドレッシング モード」を参照すること。

この結果、同一のテクスチャ アドレスを異なるテクスチャの異なるテクセルにマッピングできる。次の図では、テクスチャ アドレス (0.5,1.0) を使用している。しかし、これらのテクスチャはサイズが異なるため、テクスチャ アドレスは異なるテクセルにマッピングされる。左側のテクスチャ 1 は 5x5 である。テクスチャ アドレス (0.5,1.0) はテクセル (2,4) にマッピングされる。右側のテクスチャ 2 は 7x7 である。テクスチャ アドレス (0.5,1.0) はテクセル (3,6) にマッピングされる。

次の図は、簡単なテクセル マッピング処理を示している実際、これは非常に単純な例である。詳細については、「テクセルとピクセル間の直接マッピング」を参照すること。

この例では、図の左側のピクセルを観念化して色付きの正方形で示す。このピクセルの 4 つの角のアドレスは、オブジェクト空間の 3D プリミティブにマッピングされる。ピクセルの形状は、3D 空間のプリミティブの形状と表示角度が原因で歪むことが多い。次に、ピクセルの角に対応する、プリミティブ上のサーフェス領域の角が、テクスチャ空間にマッピングされる。このマッピング処理によってピクセルの形状が再び歪むが、これが一般的である。ピクセルの最終的なカラー値は、ピクセルがマッピングされる領域のテクセルから計算される。テクスチャ フィルタリング メソッドを設定するときに Direct3D がピクセル カラーを得るために使用するメソッドを決める。詳細については、「テクスチャ フィルタリング」を参照すること。

アプリケーションは、テクスチャ座標を直接頂点に割り当てることができる。この機能によって、プリミティブにマッピングするテクスチャの部分を決めることができる。たとえば、次の図のテクスチャとまったく同じサイズの矩形プリミティブを作成する場合を考える。この例では、アプリケーションでテクスチャ全体を壁全体にマッピングする。アプリケーションがプリミティブの頂点に割り当てるテクスチャ座標は、(0.0,0.0)、(1.0,0.0)、(1.0,1.0)、および (0.0,1.0) である。

壁の高さを 1/2 だけ小さくする場合は、小さな壁に合わせてテクスチャを歪めるか、Direct3D がテクスチャの下半分を使用するようにテクスチャ座標を割り当てることができる。

小さな壁に合わせてテクスチャを歪めたり、スケーリングしたりする場合、使用するテクスチャ フィルタリング メソッドによって画質が変わる。詳細については、「テクスチャ フィルタリング」を参照すること。

Direct3D で小さな壁に対してテクスチャの下半分を使用するようにテクスチャ座標を割り当てる場合、アプリケーションがこのプリミティブの頂点に割り当てるテクスチャ座標は、(0.0,0.0)、(1.0,0.0)、(1.0,0.5)、および (0.0,0.5) になる。Direct3D は、テクスチャの下半分を壁に適用する。

頂点のテクスチャ座標が 1.0 を超えていてもかまわない。0.0 ～ 1.0 の範囲外のテクスチャ座標を頂点に割り当てるときは、テクスチャ アドレッシング モードも設定しなければならない。詳細については、「テクスチャ アドレッシング モード」を参照すること。


テクセルとピクセル間の直接マッピング

スクリーン上のピクセルにテクセルを直接マッピングするなど、アプリケーションでは通常、シーン内のジオメトリにテクスチャを適用する必要がある。たとえば、テクスチャ内のテキストをシーン内のオブジェクトに表示する必要があるアプリケーションを考える。テクスチャ内のテキスト情報をはっきりと表示するには、テクスチャを施すジオメトリが、テクスチャ フィルタリングによって崩れていないテクセルを確実に受け取るための何らかの方法が必要である。これが行われないと、ぼんやりした画像になったり、ポイント サンプル テクスチャ フィルタリングの場合にはエッジが粗くなる可能性がある。

Microsoft® Direct3D® では、画像とテクスチャのフィルタリングをサポートする一方で、ピクセルとテクスチャのサンプリング ルールは、ピクセルとテクスチャのサンプリングを単一化するように慎重に定義されているため、テクスチャのテクセルを取得してスクリーン上のピクセルに直接マッピングする処理は重要で、困難な作業になることが多い。そのため、頂点に対する浮動小数点テクスチャ座標が、ラスタライザで使用する整数ピクセル座標にどのようにマッピングされるかについて十分に理解しておく必要がある。

Direct3D では、次の計算を実行して、浮動小数点テクスチャ座標をテクセル アドレスにマッピングする。

これらの公式では、Tx と Ty は水平方向と垂直方向の出力テクセル座標、u と v は頂点に対して提供される水平方向と垂直方向のテクスチャ座標である。Mx と My 要素は、現在のミップマップ レベルでの水平方向と垂直方向のテクセル数を表す。説明の後半では、テクセルとピクセル間の水平方向マッピングについて解説する。垂直方向マッピングは水平方向にマッピングする場合と同じである。

テクスチャ座標の上限と下限の 0.0 と 1.0 をこれらの公式に代入すると、テクスチャ座標 0.0 は反復テクスチャ マップの最初と最後のテクセル間の中間点にマッピングされる。テクスチャ座標 1.0 は、現在の補間テクスチャ マップの最後のテクセルと次の補間テクスチャ マップ間の中間点にマッピングされる。テクセル幅が 4 の反復テクスチャで、ミップマップ レベルが 0 の場合、座標 0.0 と 1.0 は、次の図に示すようにマッピングされる。

マッピングについて理解しておくと、単純なバイアスをスクリーン空間のジオメトリ座標に適用して、各テクセルを対応するピクセルに強制的にマッピングすることができる。たとえば、4 つの辺があるポリゴンで、前のテクスチャの各テクセルをスクリーン上の 1 つだけのピクセルにマッピングする場合、ジオメトリ座標でピクセルを強制的にオーバーラップして、各テクセルの中心を各ピクセルの中心に効果的に配置する必要がある。この結果、アプリケーションで多くの場合必要な 1 対 1 マッピングになる。

テクセル幅が 4 のテクスチャをピクセル座標 0 ～ 3 にマッピングするには、それぞれスクリーン空間座標 –0.5 ～ 3.5 とテクスチャ座標 0.0 ～1.0 を持つ 4 辺から成るポリゴンを、2 つの三角形を基に描画する。たとえば、スクリーン座標 0.0 にあるピクセルを例として考える。0.0 は最初の頂点 (-0.5) から 0.5 ピクセルだけ離れた位置座標にあり、合計幅が 4.0 であることから、補間テクスチャの座標は 0.125 になる。これをテクスチャ サイズ 4 を基にスケーリングすると、座標は 0.5 になる。バイアスを 0.5 だけ減じるとテクスチャ アドレスが 0.0 になる。これは、マップ内の最初のテクセルに完全に対応する。

要約すると、テクスチャ座標はテクスチャ マップを両側で均等にオーバーラップする。次の図は、テクセル幅が 4 のテクスチャのマッピングを示している。

ピクセル座標は、テクセルの場合と同様に正規化される。したがって、頂点がレンダリング先のピクセルをオーバーラップし、その頂点でテクスチャ座標 0.0 と 1.0 を使用する場合、ピクセルとテクセルが一列に並ぶ。両方のサイズがほぼ同じで適切に整列していれば、次の図に示すように、これらはテクセルとピクセル間で正確に対応する。


テクスチャ座標フォーマット

Microsoft® Direct3D® のテクスチャ座標には、1、2、3、または 4 つの浮動小数点要素を含めて、さまざまな大きさのテクスチャを処理できる。1D テクスチャ (大きさが 1 x n のテクスチャ サーフェス) の場合は、1 つのテクスチャ座標で処理される。最も一般的な 2D テクスチャの場合は、通常 u と v と呼ばれる 2 つのテクスチャ座標によって処理される。Direct3D では、キューブ環境マップという 3D テクスチャを 1 種類のみサポートしている。キューブ環境マップは、実際には 3D ではないが、3 要素ベクトルによって処理される。詳細については、「キューブ環境マップ」を参照すること。

「頂点フォーマットについて」で説明するように、アプリケーションでは頂点フォーマット内のテクスチャ座標をエンコードする。頂点フォーマットにはテクスチャ座標の複数のセットを含めることができる。D3DFVF_TEX0 ～ D3DFVF_TEX8 柔軟な頂点フォーマット フラグを使用して、テクスチャ座標を含めないか、最大 8 つのセットまで含めることを指定する。

各テクスチャ座標セットには、1 ～4 つの要素を含めることができる。この SDK 付属の Math.bas ソース ファイルにあるヘルパー関数 D3DFVF_TEXCOORDSIZEn セットを使用して、頂点フォーマットのテクスチャ座標セットで使用される要素の個数を記述するビット パターンを作成する。これらのマクロは、要素数を定義する座標セットのインデックスを識別するパラメータを 1 つ受け取る。次の図は、これらのマクロの使用方法を示している。

Private Sub Form_Load()
' この頂点フォーマットには、2 つのテクスチャ座標セットが含まれている。
' 1 つ目のセット (インデックス 0) には 2 つの要素があり、2 つ目のセットには
' 1 つの要素がある。
'
' この頂点フォーマットは次のように記述される。
'     lFVF = D3DFVF_XYZ Or D3DFVF_NORMAL Or D3DFVF_DIFFUSE Or D3DFVF_TEX2 Or _
'            D3DFVF_TEXCOORDSIZE2(0) Or D3DFVF_TEXCOORDSIZE1(1)
Type CustomVertexFormat
    position As D3DVECTOR
    normal As D3DVECTOR
    diffuse  As D3DVECTOR
    ' 1 つ目のセット、2D
    u As Single
    v As Single
    ' 2 つ目のセット、1D
    t As Single
End Type

注 キューブ環境マップを除き、ラスタライザでは 3 つ以上の要素を使用してテクスチャを処理することはできない。アプリケーションではテクスチャ座標に最大 3 つまで要素を指定できるが、これが可能なのは、テクスチャがキューブ マップの場合か、D3DTTFF_PROJECTED テクスチャ トランスフォーム フラグが使用されている場合のみである。D3DTTFF_PROJECTED フラグが使用されている場合、ラスタライザは最初の 2 つの要素を 3 つ目 (または n つ目) の要素で除算する。詳細については、「テクスチャ座標トランスフォーム」を参照すること。


テクスチャ座標処理

ここでは、Microsoft® Direct3D® でサポートするテクスチャ座標処理について説明する。説明するトピックは、次のとおりである。

  • テクスチャ座標処理の流れ
  • テクスチャ座標の自動生成
  • テクスチャ座標トランスフォーム
  • テクスチャ座標処理の使い方


テクスチャ座標処理の流れ

次の図は、テクスチャ座標が処理を通してラスタライザに送られるまでの流れを示している。

システムでは、2 つのソースからテクスチャ座標を描画できる。所定のテクスチャ ステージでは、頂点フォーマット (D3DFVF_TEX1 ～ D3DFVF_TEX8) に含まれるテクスチャ座標を使用するか、Microsoft® Direct3D® で自動生成したテクスチャ座標を使用できる。後者の詳細については、「テクスチャ座標の自動生成」を参照すること。現在のテクスチャ ステージの D3DTSS_TEXTURETRANSFORMFLAGS テクスチャ ステージ ステートを D3DTTFF_DISABLE (デフォルト設定) に設定すると、入力座標はトランスフォームされない。D3DTSS_TEXTURETRANSFORMFLAGS を別の値に設定すると、そのステージのトランスフォーム行列が入力座標に適用される。

CONST_D3DTEXTURETRANSFORMFLAGS 列挙は、D3DTSS_TEXTURETRANSFORMFLAGS テクスチャ ステージ ステートに有効な値を定義する。テクスチャ座標トランスフォームを実行しない D3DTTFF_DISABLE フラグを除き、この列挙に定義される値は、システムによってラスタライザに渡される出力座標の個数を設定する。D3DTTFF_COUNT1 ～ D3DTTFF_COUNT4 フラグの場合、1、2、3、または 4 つの要素が出力座標からラスタライザに渡される。

D3DTTFF_PROJECTED フラグは特別なフラグである。このフラグは、テクスチャ座標が射影テクスチャ用のものであることをシステムに知らせる。D3DTTFF_PROJECTED フラグと CONST_D3DTEXTURETRANSFORMFLAGS の別のメンバを組み合わせることで、すべての要素を最後の要素で除算してからラスタ化を実行するようにラスタライザに知らせる。たとえば、3 要素のテクスチャ座標、またはトランスフォーム後の 3 要素のテクスチャ座標を明示的に使用するとき、D3DTTFF_COUNT3 および D3DTTFF_PROJECTED フラグを組み合わせて使用すると、ラスタライザで最初の 2 つの要素を最後の要素で除算して、2D テクスチャの処理に必要な 2D テクスチャ座標を生成できる。

注 キューブ環境マップを除き、ラスタライザでは 3 つ以上の要素を使用してテクスチャを処理することはできない。カレント テクスチャを処理するために使用できる要素数よりも多くの要素をテクスチャ ステージに指定した場合、無関係な要素は無視される。これは、1D テクスチャに対して 2D テクスチャ座標を使用するときにもあてはまる。


テクスチャ座標の自動生成

Microsoft® Direct3D® では、頂点に対してテクスチャ座標を自動的に生成できる。ここでは、システムが提供する機能とその使用方法について詳しく説明する。説明するトピックは、次のとおりである。

  • テクスチャ座標の自動生成について
  • テクスチャ座標の自動生成の構成


テクスチャ座標の自動生成について

システムでは、トランスフォーム後のカメラ空間位置座標または頂点の法線をテクスチャ座標として使用できる。また、キューブ環境マップを実行するための 3 要素ベクトルを計算することも可能である。頂点で明示的に指定するテクスチャ座標と同様、自動生成されたテクスチャ座標は、テクスチャ座標トランスフォーム用の入力として使用できる。

テクスチャ座標の自動生成では、頂点フォーマットでの明示的なテクスチャ座標の必要性を排除することで、ジオメトリ データで必要となる帯域幅を大幅に削減できる。多くの場合、システムで生成されたテクスチャ座標は、特殊効果を生み出すトランスフォームと共に使用できる。もちろん、この機能は特殊な用途に使用されるものであり、明示的なテクスチャ座標を使用するケースも多くある。


テクスチャ座標の自動生成の構成

Microsoft® Visual Basic® の場合、(CONST_D3DTEXTURESTAGESTATETYPE 列挙からの) D3DTSS_TEXCOORDINDEX テクスチャ ステージ ステートを使用して、テクスチャ座標の生成方法を制御する。

通常、このステートは、頂点フォーマットで符号化された特定のテクスチャ座標セットを使用するようシステムに知らせる。このステートに割り当てる値の中に、D3DTSS_TCI_CAMERASPACENORMAL、D3DTSS_TCI_CAMERASPACEPOSITION、または D3DTSS_TCI_CAMERASPACEREFLECTIONVECTOR フラグを含めた場合、システムで実行される処理は大きく異なってくる。これらのフラグのいずれかでも存在しているとき、テクスチャ ステージは頂点フォーマットのテクスチャ座標を無視し、システムが生成する座標を優先する。各フラグの意味は、次のとおりである。

D3DTSS_TCI_CAMERASPACENORMAL
頂点法線を入力テクスチャ座標として使用する。頂点法線はカメラ空間にトランスフォームされる。
D3DTSS_TCI_CAMERASPACEPOSITION
頂点位置座標を入力テクスチャ座標として使用する。頂点位置座標がカメラ空間にトランスフォームされる。
D3DTSS_TCI_CAMERASPACEREFLECTIONVECTOR
反射ベクトルを入力テクスチャ座標として使用する。反射ベクトルがカメラ空間にトランスフォームされる。反射ベクトルは、入力頂点位置座標と法線ベクトルから計算される。

これらのフラグは互いに排他的である。これらのフラグのいずれかを使用する場合は、テクスチャ ラッピング モードを決定するためにシステムで使用するインデックス値を指定できる。

次のコードは、Visual Basic でのこれらのフラグの使用方法を示している。

'
' このコードでは、変数 D3DDevice は、Direct3DDevice8 オブジェクトへの
' 有効な参照であると仮定している。
'
' このテクスチャ ステージの入力テクスチャ座標として
' 頂点位置座標 (カメラ空間) を使用し、
' D3DRENDERSTATE_WRAP1 レンダリング ステートのラップ モード セットを使用する。
'
Call D3DDevice.SetTextureStageState( 0, D3DTSS_TEXCOORDINDEX, _
                                    D3DTSS_TCI_CAMERASPACEPOSITION Or 1 )

注 自動生成されたテクスチャ座標は、テクスチャ座標トランスフォームの入力値として非常に便利であり、またキューブ環境マップの 3 要素ベクトルを計算する必要がないという点でも便利である。

参照

テクスチャ座標トランスフォーム、キューブ環境マップ


テクスチャ座標トランスフォーム

ここでは、Microsoft® Direct3D® 直接モードで提供されるテクスチャ座標トランスフォーム機能の操作について説明する。説明するトピックは、次のとおりである。

  • テクスチャ座標トランスフォームについて
  • テクスチャ座標トランスフォームの設定と取得
  • テクスチャ座標トランスフォームを有効にする


テクスチャ座標トランスフォームについて

Microsoft® Direct3D® デバイスでは、4×4 行列を適用して、頂点のテクスチャ座標をトランスフォームできる。システムは、テクスチャ座標に対して、ジオメトリの場合と同様にトランスフォームを適用する。適用可能なトランスフォームには、スケーリング、回転、平行移動、射影、せん断、またはこれらの組み合わせなど、4×4 行列で可能なあらゆるトランスフォームがある。

注 Direct3D では、「トランスフォーム済み ライティング済みの頂点」は修正されない。したがって、「トランスフォーム済み ライティング済みの頂点」を使用するアプリケーションでは、Direct3D によって頂点のテクスチャ座標をトランスフォームすることはできない。

ハードウェア アクセラレーションによるトランスフォーム & ライティング処理をサポートするデバイス (TnLHAL デバイス) では、テクスチャ座標トランスフォームも高速処理される。ハードウェア アクセラレーションによるトランスフォームが利用できない場合は、Direct3D ジオメトリ パイプラインのプラットフォーム固有の最適化によってテクスチャ座標トランスフォームが実行される。

テクスチャ座標トランスフォームは、ジオメトリのテクスチャ座標を直接変更しないで特殊効果を出そうとする場合に便利である。単純な平行移動行列や回転行列を使用して、オブジェクト上のテクスチャをアニメーションしたり、Direct3D によって自動生成されるテクスチャ座標をトランスフォームすることで、射影テクスチャや動的ライト マッピングなど高度なエフェクトを単純化し、高速処理することも可能である。また、テクスチャ座標トランスフォームを使用して、テクスチャ座標の単一セットを複数のテクスチャ ステージでのさまざまな目的のために再利用できる。

詳細については、「テクスチャ座標処理の使い方」を参照すること。


テクスチャ座標トランスフォームの設定と取得

アプリケーションでジオメトリに使用する行列と同様、Direct3DDevice8.SetTransform および Direct3DDevice8.GetTransform メソッドを呼び出してテクスチャ座標トランスフォームを設定および取得できる。これらのメソッドは、テクスチャ ステージの 0 ～ 7 のトランスフォーム行列をそれぞれ識別する、CONST_D3DTRANSFORMSTATETYPE 列挙の D3DTS_TEXTURE0 ～ D3DTS_TEXTURE7 メンバを受け取る。

次のコードは、テクスチャ ステージ 0 のテクスチャ座標に適用される行列を設定する。

' この例では、変数 D3DDevice は
' Direct3DDevice8 オブジェクトへの有効な参照が格納されており、
' dx には DirectX8 オブジェクトへの有効な参照が格納されている。

Dim matTrans As D3DMATRIX

Call D3DXMatrixIdentity( matTrans )

' 目的のトランスフォーム用の行列を設定する。
D3dDevice.SetTransform( D3DTS_TEXTURE0, matTrans )


テクスチャ座標トランスフォームを有効にする

D3DTSS_TEXTURETRANSFORMFLAGS テクスチャ ステージ ステートは、テクスチャ座標トランスフォームの適用を制御する。このテクスチャ ステージ ステートの値は、CONST_D3DTEXTURETRANSFORMFLAGS 列挙で定義されている。

D3DTSS_TEXTURETRANSFORMFLAGS が D3DTTFF_DISABLE (デフォルト値) に設定されているときは、テクスチャ座標トランスフォームは無効である。テクスチャ座標トランスフォームがステージ 0 に対して有効な場合、次のコードはこれを無効にする。

' この例では、変数 D3DDevice に Direct3DDevice8 オブジェクトへの
' 有効な参照が格納されている。

Call D3DDevice.SetTextureStageState(0, D3DTSS_TEXTURETRANSFORMFLAGS, _
                                    D3DTTFF_DISABLE)

CONST_D3DTEXTURETRANSFORMFLAGS に定義されているその他の値は、テクスチャ座標トランスフォームを有効にするため、また、結果として生成されるテクスチャ座標の要素のうち、ラスタライザに渡す個数を制御するために使用する。例として次のコードを考える。

' この例では、変数 D3DDevice に Direct3DDevice8 オブジェクトへの
' 有効な参照が格納されている。

Call D3DDevice.SetTextureStageState(0, D3DTSS_TEXTURETRANSFORMFLAGS, _
                                    D3DTTFF_COUNT2)

D3DTTFF_COUNT2 値は、テクスチャ ステージ 0 用のトランスフォーム行列セットを適用し、トランスフォーム後のテクスチャ座標の最初の 2 つの要素をラスタライザに渡すようシステムに指示する。

D3DTTFF_PROJECTED テクスチャ トランスフォーム フラグは、射影されるテクスチャの座標を示す。このフラグが指定されている場合、ラスタライザはトランスフォーム対象の要素を最後の要素で除算する。例として次のコードを考える。

' この例では、変数 D3DDevice に IDirect3DDevice8 インターフェイスへの
' 有効なポインタが格納されている。

Call D3DDevice.SetTextureStageState(0, D3DTSS_TEXTURETRANSFORMFLAGS, _
                                    D3DTTFF_COUNT3 | D3DTTFF_PROJECTED)

この例では、3 つのテクスチャ座標要素をラスタライザに渡すようにシステムに知らせる。ラスタライザでは、最初の 2 つの要素を 3 つ目の要素で除算して、テクスチャの処理に必要な 2D テクスチャ座標を生成する。


テクスチャ座標処理の使い方

次に示すのは、テクスチャ座標処理によって特殊なテクスチャ エフェクトを出す方法である。

モデル上でテクスチャをアニメーションする (平行移動または回転を利用)

  • 2D テクスチャ座標を頂点フォーマットに定義する。
    ' 2D テクスチャ座標を持つ単一のテクスチャを使用する。このビット パターンは、
' 必要に応じて、位置座標、法線、および色情報を追加できるように
' 拡張する必要がある。
lFVFTex = (D3FVF_TEX1 Or D3DFVF_TEXCOORDSIZE2(0))
  • 2D テクスチャ座標を使用するようにラスタライザを設定する。
    SetTextureStageState(0, D3DTSS_TEXTURETRANSFORMFLAGS, D3DTTFF_COUNT2)
  • 適切なテクスチャ座標トランスフォーム行列を定義して設定する。
    ' M は、U および V 方向のテクスチャ座標を平行移動するための
' D3DMATRIX である。
'      1   0  0  0
'      0   1  0  0
'      du dv  0  0 (du および dv は各フレームを変更する)
'      0   0  0  0
dx.IdentityMatrix(M)
M.rc31 = du
M.ec32 = dv

モデルのカメラ空間位置座標の線形関数としてテクスチャ座標を作成する

  • D3DTSS_TCI_CAMERASPACEPOSITION フラグを使用して、カメラ空間の頂点位置座標を入力としてテクスチャ トランスフォームに渡す。
    ' 入力頂点にはテクスチャ座標がなく、
' 帯域幅が節約されている。3 つのテクスチャ座標は、カメラ空間 (x, y, z) の頂点位置座標を使用して
' 生成される。
SetTextureStageState(0, D3DTSS_TEXCOORDINDEX, D3DTSS_TCI_CAMERASPACEPOSITION)
  • ラスタライザで 2D テクスチャ座標を評価する。
    ' 2 つの出力座標が使用される。
SetTextureStageState(0, D3DTSS_TEXTURETRANSFORMFLAGS, D3DTTFF_COUNT2)
  • 線形関数を適用する行列を定義して設定する。
    ' 次に示すように、
' テクスチャ座標を線形関数として生成する。
'      u = Ux*x + Uy*x + Uz*x + Uw
'      v = Vx*x + Vy*x + Vz*x + Vw
' この場合、行列 M は次のようになる。
'      Ux  Vx  0  0
'      Uy  Vy  0  0
'      Uz  Vz  0  0
'      Uw  Vw  0  0

SetTransform(D3DTS_TEXTURE0, M)

キューブ環境マップによる環境マッピングを実行する

  • D3DTSS_TCI_CAMERASPACEREFLECTIONVECTOR フラグを使用して、キューブ マップ用の反射ベクトルとしてテクスチャ座標を自動的に生成する。
    SetTextureStageState(0, D3DTSS_TEXCOORDINDEX, D3DTSS_TCI_CAMERASPACEREFLECTIONVECTOR)
  • ラスタライザに、3 つの要素を持つテクスチャ座標を使用するよう指示する。
    SetTextureStageState(0, D3DTSS_TEXTURETRANSFORMFLAGS, D3DTTFF_COUNT3)

射影テクスチャを実行する

  • D3DTSS_TCI_CAMERASPACEPOSITION フラグを使用して、テクスチャ トランスフォームに頂点位置座標を入力として渡す。
    SetTextureStageState(0, D3DTSS_TEXCOORDINDEX, D3DTSS_TCI_CAMERASPACEPOSITION)
  • テクスチャ射影行列を作成して適用する。これはドキュメントの対象外であり、その他の市販製品で扱う内容である。
  • ラスタライザに 3 つの要素を持つ射影テクスチャ座標を使用するよう指示する。
    ' 2 つの出力座標を使用する。
SetTextureStageState(0, D3DTSS_TEXTURETRANSFORMFLAGS, D3DTTF_PROJECTED | D3DTTFF_COUNT3)


テクスチャ リソース

ここでは、テクスチャ インターフェイス ポインタによる作成およびレンダリングについて説明する。説明するトピックは、次のとおりである。

  • テクスチャ サーフェス オブジェクトの取得
  • テクスチャ リソースを使用したレンダリング


テクスチャ サーフェス オブジェクトの取得

テクスチャ リソースは、Direct3DTexture8 クラスに実装されている。テクスチャ オブジェクトを取得するには、Direct3DDevice8.CreateTexture メソッドか、次のいずれかの D3DX 関数を呼び出す。

  • D3DX8.CreateTexture
  • D3DX8.CreateTextureFromFile
  • D3DX8.CreateTextureFromFileEx
  • D3DX8.CreateTextureFromFileInMemory
  • D3DX8.CreateTextureFromFileInMemoryEx
  • D3DX8.CreateTextureFromResource
  • D3DX8.CreateTextureFromResourceEx

次のコードでは、D3DX.CreateTextureFromFile を使用して、Tiger.bmp というファイルからテクスチャをロードする。

'
' 次のコードでは、d3dDevice は有効な Direct3DDevice8 オブジェクトであり、
' g_D3DX も
' 有効であると仮定している。
'
Dim Texture As Direct3DTexture8

Set Texture = g_D3DX.CreateTextureFromFile( d3dDevice, App.Path + "\tiger.bmp" )

CreateTextureFromFile が受け取る第 1 パラメータは、Direct3DDevice8 オブジェクトである。第 2 パラメータは、ロードするテクスチャが入っているファイル名を Microsoft® Direct3D® に指示する。このメソッドが返すテクスチャ オブジェクトは、Texture に割り当てられる。


テクスチャ リソースを使用したレンダリング

Microsoft® Direct3D® では、テクスチャ ステージという概念を用いてマルチ テクスチャ ブレンディングをサポートする。テクスチャ ステージごとに、テクスチャとそのテクスチャで実行可能な処理がある。テクスチャ ステージのテクスチャは、カレント テクスチャの集まりを形成する。詳細については、「マルチ テクスチャ ブレンディング」を参照すること。各テクスチャのステートは、そのテクスチャ ステージにカプセル化される。

Microsoft® Visual Basic® では、各テクスチャのステートは Direct3DDevice8.SetTextureStageState メソッドで設定する必要がある。第 1 パラメータの値としてステージ番号 (0 ～ 7) を渡す。第 2 パラメータの値には、CONST_D3DTEXTURESTAGESTATETYPE 列挙のメンバを設定する。最後のパラメータは、特定のテクスチャ ステートについてのステート値である。

アプリケーションでは、最大 8 つのテクスチャのブレンドをレンダリングできる。Direct3DDevice8.SetTexture メソッドを呼び出してカレント テクスチャを設定する。Direct3D は、レンダリングするプリミティブに対して、カレント テクスチャをすべてブレンドする。

注 テクスチャが不要になった場合、該当するステージのテクスチャを Nothing に設定する必要がある。これを行わなかった場合、アプリケーションを閉じたときにサーフェス用のメモリが失われることがある。

Direct3DDevice8.SetRenderState メソッドを呼び出して、カレント テクスチャのテクスチャ ラッピング ステートを設定できる。第 1 パラメータの値として、D3DRENDERSTATE_WRAP0 ～ D3DRENDERSTATE_WRAP7 の値を 1 つ渡す。また、CONST_D3D 列挙からの D3DWRAPCOORD_0、D3DWRAPCOORD_1、D3DWRAPCOORD_2、および D3DWRAPCOORD_3 フラグ の組み合わせを使用して、u または v 方向のラッピングを有効にする。

また、テクスチャ パースペクティブ ステートとテクスチャ フィルタリング ステートを設定することもできる。「テクスチャ フィルタリング」および「テクスチャ フィルタリング ステート」を参照すること。


テクスチャ フィルタリング

Microsoft® Direct3D® はプリミティブをレンダリングするとき、3D プリミティブを 2D スクリーンにマッピングする。プリミティブがテクスチャを持っている場合、Direct3D はそのテクスチャを使用して、プリミティブの 2D レンダリング画像の各ピクセルの色を生成しなければならない。プリミティブのスクリーン上の画像のすべてのピクセルに対して、テクスチャからカラー値を取得しなければならない。この処理をテクスチャ フィルタリングと呼ぶ。

テクスチャ フィルタリング処理を実行するとき、使用するテクスチャは通常拡大または縮小される。つまり、テクスチャは、それ自体よりも大きなまたは小さなプリミティブ画像にマッピングされる。テクスチャの拡大によって、多数のピクセルが 1 つのテクセルにマッピングされることがある。この結果、画像が粗くなることがある。テクスチャの縮小では、多くの場合、単一のピクセルが多数のテクセルにマッピングされる。この結果、画像が不鮮明になったり、ぎざぎざができることがある。これらの問題を解決するには、ピクセルの色になるようにテクセル色のブレンディングを実行する必要がある。

Direct3D では、テクスチャ フィルタリングの複雑な処理を簡素化する。Direct3D では、線形フィルタリング、異方性フィルタリング、およびミップマップ フィルタリングの 3 種類のテクスチャ フィルタリングを使用できる。テクスチャ フィルタリングを選択しない場合、Direct3D では最近ポイント サンプリングという方法を使用する。

それぞれのテクスチャ フィルタリングには、長所と短所がある。たとえば、線形テクスチャ フィルタリングを使用した場合、最終的な画像でエッジがぎざぎざになったり、画質が粗くなることがある。しかし、このフィルタリングはオーバーヘッドが少ない。ミップマップによるフィルタリングを使用すると、通常は最良の結果が得られる。特に、異方性フィルタリングと組み合わせて使用した場合はそうである。しかし、このフィルタリングは、Direct3D がサポートする方法の中で最もメモリを必要とするものである。

Microsoft® Visual Basic® アプリケーションでは、Direct3DDevice8.SetTextureStageState メソッドを呼び出して現在のテクスチャ フィルタリング方法を設定する必要がある。第 1 パラメータの値を、テクスチャ フィルタリング方法を選択するテクスチャの整数インデックス番号 (0 ～ 7) に設定する。第 2 パラメータとして CONST_D3DTEXTUREMAGFILTER、CONST_D3DTEXTUREMINFILTER、または CONST_D3DTEXTUREMIPFILTER を渡して、拡大、縮小、またはミップマップ フィルタを設定する。第 3 パラメータを、CONST_D3DTEXTUREFILTERTYPE の値に設定して、拡大、縮小、またはミップマップ フィルタを設定する。

ここでは、Direct3D でサポートするテクスチャ フィルタリング方法について説明する。説明するトピックは、次のとおりである。

  • 最近点サンプリング
  • 線形テクスチャ フィルタリング
  • 異方性テクスチャ フィルタリング
  • ミップマップによるテクスチャ フィルタリング


最近点サンプリング

アプリケーションでは、このテクスチャ フィルタリングを使用する必要はない。Microsoft® Direct3D® は、テクセル アドレスを計算 (このアドレスは整数でないことが多い) したり、この値に最も近い整数アドレスを持つテクセルの色を単にコピーするように設定できる。この処理を最近点サンプリングと呼ぶ。テクスチャのサイズがスクリーン上のプリミティブの画像のサイズとほぼ同じ場合には、この方法によってテクスチャは高速で効率的に処理できる。両方のサイズの差が大きい場合は、テクスチャを拡大したり、縮小する必要がある。このような処理を実行した結果、画像が粗くなったり、ぎざぎざができたり、不鮮明になることがある。

Microsoft® Visual Basic® アプリケーションでは、Direct3DDevice8.SetTextureStageState メソッドを呼び出して最近点サンプリングを選択できる。第 1 パラメータの値を、テクスチャ フィルタリング方法を選択するテクスチャの整数インデックス番号 (0 ～ 7) に設定する。第 2 パラメータとして CONST_D3DTEXTUREMAGFILTER、CONST_D3DTEXTUREMINFILTER、または CONST_D3DTEXTUREMIPFILTER を渡して、拡大、縮小、またはミップマップ フィルタを設定する。第 3 パラメータの値として CONST_D3DTEXTUREFILTERTYPE 列挙型のメンバを渡して、拡大、縮小、またはミップマップ フィルタを設定する。

詳細については、「テクスチャ フィルタリング ステート」を参照すること。

最近点サンプリングは注意して使用すること。2 つのテクセル間の境界でテクスチャがサンプリングされる際、場合によっては不自然なグラフィックス効果が生じることがある。この境界とは、サンプリング対象のテクセルが次のテクセルに移るときの、テクスチャに沿った位置座標 (u または v) である。ポイント サンプリングを使用するとき、システムではサンプル テクセルを 1 つ選択するか、別のテクセルを選択する。これにより、境界が交差している際は結果がテクセル間で不意に変化することがある。この影響から、表示されるテクスチャの中に、好ましくない不自然なグラフィックス エフェクトが現れることがある。線形フィルタリングを使用した場合、結果テクセルは隣接テクセル間で計算され、テクスチャ インデックスが境界に沿って移るのに従って滑らかにブレンドされる。

このようなエフェクトは、非常に小さなテクスチャを非常に大きなポリゴンにマッピングする (多くの場合 "拡大" と呼ぶ) ときに発生する可能性がある。たとえば、チェッカー盤のようなテクスチャでポイント サンプリングを使用すると、チェッカー盤は拡大されてエッジが際立つ。対照的に、線形テクスチャ フィルタリングを使用した場合は、チェッカー盤の色がポリゴン全体にわたって滑らかに変化した画像ができあがる。

ほとんどの場合、最良の結果を得るためには、最近点サンプリングの使用をできるだけ避けるようにする。最近のハードウェアのほとんどは、線形フィルタリング用に最適化されているため、パフォーマンスが低下することはない。ただし、テクスチャを使用して読みやすいテキスト文字を表示する場合など、目的のエフェクトを出すためにどうしても最近点サンプリングを使用しなければならない場合は、テクセル境界でサンプリングを行わないように心がけ、思わぬエフェクトが生じないよう細心の注意を払う必要がある。次の図は、不自然なグラフィックス効果がどのようなものであるかを示している。

グループ内の右上にある 2 つの四角形が隣接する四角形とは異なることに注意する。これらには対角オフセットがある。このような不自然なグラフィックス効果を避けるためには、まず最近点フィルタリングに関する Direct3D テクスチャ サンプリング ルールについて理解する必要がある。Direct3D では、[0.0, 1.0] (0.0 ～ 1.0 まで含む) の範囲内の浮動小数点テクスチャ座標を、[–0.5, n – 0.5] の範囲内の整数テクセル空間値にマッピングする。ここで、n はテクスチャの所定の大きさでのテクセル数である。結果のテクスチャ インデックスは、最も近い整数に丸められる。このマッピングにより、テクスチャ境界ではサンプリングの誤差が生じる場合がある。

簡単な例として、D3DTADDRESS_WRAP テクスチャ アドレッシング モードでポリゴンをレンダリングする場合を考えてみる。Direct3D のマッピングを使用すると、u テクスチャ インデックスは、4 テクセル幅のテクスチャに対して、次のようにマッピングされる。

この図で、テクスチャ座標 0.0 と 1.0 は、テクセル間の境界上に正確に位置する。Direct3D のマッピング用のメソッドを使用すると、テクスチャ座標は [–0.5, 4 – 0.5] の範囲内にマッピングされる。ここで、4 はテクスチャの幅である。この場合、サンプリングされるのは、テクスチャ インデックス 1.0 の 0 番目のテクセルである。ただし、テクスチャ座標が 1.0 よりもわずかに少ない場合には、サンプリングされるのは 0 番目のテクセルではなく、n 番目のテクセルになる。

これは、つまり、テクスチャ座標 0.0 と 1.0 を持つ小さなテクスチャを、スクリーン空間に配列された三角形上で最近点フィルタリングによって拡大すると、その結果、テクスチャ マップがテクセル間の境界でサンプリングされる際の対象となるピクセルになる、という意味である。テクスチャ座標の計算の誤差がわずかな場合であっても、テクスチャ マップのテクセル エッジに対応する、レンダリング画像の領域に沿って不自然な効果が現れる。

このように浮動小数点テクスチャ座標を整数テクセルに完璧に正確にマッピングするのは、困難な作業であり、計算負荷も大きいが、このような処理を一般には行う必要はない。ほとんどのハードウェア実装では、三角形内の各ピクセル位置座標におけるテクスチャ座標の計算に反復処理を用いる。この方法を使用すると、補間処理間で誤差が均等に累積されていくため、これらの誤差がいくらかは目立たなくなる。

Direct3D リファレンス ラスタライザでは、各ピクセル位置座標でのテクスチャ インデックスの計算に直接評価法を用いる。直接評価は反復処理とは異なり、処理上の誤差がよりランダムなエラー分布を示す。この結果、境界上ではより顕著なサンプリング エラーが発生する。これは、リファレンス ラスタライザによってこの処理が正確に実行されないためである

最近点フィルタリングは、必要な場合にのみ使用するとよい。これを使用する必要がある場合は、テクスチャ座標を境界位置座標から少しだけオフセットして不自然な効果の発生を防ぐことが推奨される。


線形テクスチャ フィルタリング

Microsoft® Direct3D® では、バイリニア フィルタリングと呼ばれる線形テクスチャ フィルタリングを使用する。最近点サンプリングと同様、バイリニア テクスチャ フィルタリングでは最初にテクセル アドレスを計算するが、通常、この値が整数アドレスになることはない。バイリニア フィルタリングでは、計算したアドレスに最も近い整数アドレスを持つテクセルが検索される。さらに、Direct3D レンダリング モジュールでは、サンプリングした最近点の上下左右にあるテクセルの加重平均を計算する。

Direct3DDevice8.SetTextureStageState メソッドを呼び出して、バイリニア テクスチャ フィルタリングを選択する。第 1 パラメータの値を、テクスチャ フィルタリング方法を選択するテクスチャの整数インデックス番号 (0 ～ 7) に設定する。第 2 パラメータとして CONST_D3DTEXTUREMAGFILTER、CONST_D3DTEXTUREMINFILTER、または CONST_D3DTEXTUREMIPFILTER を渡して、拡大、縮小、またはミップマップ フィルタを設定する。第 3 パラメータを D3DTEXF_LINEAR に設定する。詳細については、「テクスチャ フィルタリング ステート」を参照すること。


異方性テクスチャ フィルタリング

異方性とは、スクリーン平面に対して角度をなして位置したサーフェスを持つ 3D オブジェクトのテクセルの可視的なゆがみである。異方性プリミティブからのピクセルをテクセルにマッピングするとき、プリミティブの形状がゆがむ。Microsoft® Direct3D® では、テクスチャ空間に逆マッピングされるスクリーン ピクセルの伸長度 (長さ÷幅) としてピクセルの異方性を測定する。

異方性テクスチャ フィルタリングは、線形テクスチャ フィルタリングまたはミップマップ テクスチャ フィルタリングと併用することで、レンダリング結果を向上させることができる。Direct3DDevice8.SetTextureStageState メソッドを呼び出して、異方性テクスチャ フィルタリングを有効にする。第 1 パラメータの値を、テクスチャ フィルタリング方法を選択するテクスチャの整数インデックス番号 (0 ～ 7) に設定する。第 2 パラメータとして CONST_D3DTEXTUREMAGFILTER、CONST_D3DTEXTUREMINFILTER、または CONST_D3DTEXTUREMIPFILTER を渡して、拡大、縮小、またはミップマップ フィルタを設定する。第 3 パラメータを D3DTEXF_ANISOTROPIC に設定する。詳細については、「テクスチャ フィルタリング ステート」を参照すること。

また、異方性の度合いをゼロより大きな値に設定する必要がある。これを設定するには、Direct3DDevice8.SetTextureStageState メソッドを呼び出す。第 1 パラメータには、異方性の度合いを設定するテクスチャの整数インデックス番号 (0 ～ 7) を設定する。第 2 パラメータには、D3DTSS_MAXANISOTROPY を渡す。最後のパラメータは、異方性の度合いでなければならない。

異方性の度合いを 1 に設定すると、異方性フィルタリングが無効になり、1 より大きな値を設定すると、異方性フィルタリングが有効になる。異方性の度合いとして設定可能な値の範囲を調べるには、D3DCAPS8 型の MaxAnisotropy フラグをチェックする。


ミップマップによるテクスチャ フィルタリング

ミップマップ テクスチャは、シーンのレンダリングに必要な時間を短縮するために 3D シーンで使用される。また、ミップマップ テクスチャを使用すると、シーンのリアリティが増す。しかし、ミップマップ テクスチャを使用するにはメモリが大量に必要となることが多い。

ここでは、3D シーンでのミップマップ テクスチャの使用に関する基本事項について説明する。説明するトピックは、次のとおりである。

  • ミップマップとは
  • ミップマップ セットの作成
  • ミップマップの選択と表示


ミップマップとは

ミップマップとは連続したテクスチャで、各テクスチャは同じ画像を徐々に低解像度にしたものである。ミップマップでの各画像の高さと幅、つまりレベルは、直前のレベルよりも 2 の累乗だけ小さい。ミップマップは正方形である必要はない。

ユーザーに近いオブジェクトには、高解像度ミップマップ画像が使用される。オブジェクトが遠ざかるに従って、低解像度のミップマップ画像が使用される。ミップマップ処理により、レンダリングしたテクスチャの品質が向上するが、使用するメモリは増加する。

Microsoft® Direct3D® では、ミップマップはアタッチされたサーフェスのチェーンとして表される。このチェーンの先頭には最高解像度のテクスチャがあり、その後には次のミップマップ レベルのテクスチャが続く。このレベルの後には次のレベルのミップマップが続く、という順に最低解像度のミップマップになるまで続いていく。

次の図は、これらのレベルの例を示している。ビットマップ テクスチャは、対面型のゲームの 3D コンテナの側面にある記号を表している。ミップマップとして作成すると、最高解像度のテクスチャがこのセットの先頭にくる。このミップマップ セットの連続する各テクスチャは、高さと幅が 2 の累乗ずつ小さくなっていく。この場合、最高解像度のミップマップは 256x256 ピクセルである。次のテクスチャは 128x128 である。最後のテクスチャは 64x64 である。

この記号は可視範囲内の最大距離にある。この記号から遠く離れた位置からゲームを開始する場合、ミップマップ チェーンの中で最小のテクスチャ (この場合 64x64 テクスチャ) が表示される。

ユーザーの視点がこの記号に近づくにつれて、徐々に高解像度のテクスチャが使用される。次の図の解像度は 128x128 である。

最高解像度のテクスチャが使用されるのは、プレーヤーの視点がこの記号に最も近づいたときである。

これは、テクスチャのパースペクティブをシミュレートする方法の中ではオーバーヘッドが低い方法である。1 つのテクスチャを多くの解像度でレンダリングするよりも、さまざまな解像度で複数のテクスチャを使用する方が高速である。

Direct3D では、ミップマップ セットの中でどのテクスチャが最も目的出力に近い解像度であるかを評価し、ピクセルをそのテクセル空間にマッピングできる。最終的な画像の解像度がミップマップ セット内のテクスチャ間にある場合、Direct3D では両方のミップマップのテクセルを調べ、そのカラー値をブレンドする。

ミップマップを使用するには、アプリケーションでミップマップのセットを作成する必要がある。詳細については、「ミップマップ セットの作成」を参照すること。アプリケーションでは、ミップマップ セットをカレント テクスチャ セットの最初のテクスチャとして選択して、ミップマップを適用する。詳細については、「マルチ テクスチャ ブレンディング」を参照すること。

次に、Direct3D でテクセルのサンプリングに使用するフィルタリング方法を設定しなければならない。最も処理が速いミップマップ フィルタリングは、Direct3D で最も近いテクセルを選択する方法である。これ選択するには、D3DTFP_POINT 列挙値を使用する。Direct3D では、D3DTFP_LINEAR 列挙値を使用すると、より高品質なフィルタリング結果が得られる。このフィルタリングでは、最も近いミップマップが選択され、次に現在のピクセルがマッピングされる、テクスチャ内の位置座標の周辺テクセルの加重平均が計算される。


ミップマップ セットの作成

次の例は、Direct3DDevice8.CreateTexture を呼び出して、サイズ 256 × 256、128 × 128、64 × 64、32 × 32、および 16 × 16 の 5 つのミップマップ レベルのチェーンを作成する方法を示している。

' このサンプル コードでは、変数 m_D3D は Direct3DDevice8 オブジェクトへの
' 有効な参照を格納すると仮定している。
Dim DDMipmap as Direct3DTexture8

Set DDMipmap = m_D3D.CreateTexture(256, 256, 5, 0, D3DFMT_R8G8B8, D3DPOOL_DEFAULT)

CreateTexture が受け取る最初の 2 つのパラメータは、最上位テクスチャのサイズと幅である。第 3 パラメータには、テクスチャのレベル数を指定する。このパラメータをゼロに設定すると、Microsoft® Direct3D® はサーフェスのチェーンを作成する。各サーフェスは、直前のサーフェスよりも 2 の累乗ずつ小さくなり、最終的に 1 × 1 の最小サイズになる。第 4 パラメータには、このリソースの使用方法を指定する。ここではゼロが指定されているので、リソースには特定の使用方法はないことを示す。第 5 パラメータには、テクスチャのサーフェス フォーマットを指定する。このパラメータには、CONST_D3DFORMAT 列挙型の値を使用する。第 6 パラメータには、作成したリソースを配置するメモリ クラスを示す CONST_D3DPOOL 列挙型のメンバを指定する。動的テクスチャを使用しているのでなければ、D3DPOOL_MANAGED を勧める。

注 ミップマップ チェーンの各サーフェスの大きさは、直前のサーフェスの半分になる。最上位ミップマップの大きさが 256 × 128 の場合、2 番目のレベルのミップマップの大きさは 128 × 64 になり、3 番目のレベルは 64 × 32 という順にミップマップの大きさは小さくなり、最終的には 1 × 1 になる。Levels でミップマップ レベルの数を指定することはできない。Levels では、チェーンのミップマップの幅または高さのいずれかが 1 より小さくなることがある。4 × 2 を最上位ミップマップ サーフェスとする単純なケースでは、Levels の最大値は 3 になる。最上位の大きさは 4 × 2 で、次のレベルの大きさは 2 × 1 で、その次のレベルの大きさは 1 × 1 である。Levels の値が 3 より大きいと、第 2 レベルのミップマップの高さは分数になる。したがって、これは許可されない。


ミップマップの選択と表示

Direct3DDevice8.SetTexture メソッドを呼び出して、カレント テクスチャの一覧内の先頭のテクスチャとしてミップマップ テクスチャを設定する。詳細については、「マルチ テクスチャ ブレンディング」を参照すること。

ミップマップ テクスチャ セットを選択した後、CONST_D3DTEXTUREFILTERTYPE 列挙型からの値を D3DTSS_MIPFILTER テクスチャ ステージ ステートに割り当てなければならない。Microsoft® Direct3D® ではミップマップ テクスチャ フィルタリングを自動的に実行する。次のサンプル コードでは、ミップマップ テクスチャ フィルタリングが有効にされている。

m_D3D.SetTexture(0, DDMipMap)
m_D3D.SetTextureStateState(0, D3DTSS_MIPFILTER, D3DTEXF_POINT)

また、Direct3DTexture8.GetSurfaceLevel メソッドを使用し、取得するミップマップ レベルを指定することで、ミップマップ サーフェスのチェーンを手動でトラバースできる。次の例では、最高解像度から最低解像度までミップマップ チェーンをトラバースする。

Dim DDLevel As Direct3DSurface8
Dim cLevels As Long

cLevels = DDMipMap.GetLevelCount

For iLevel = 0 to cLevels
    Set DDLevel = DDMipMap.GetSurfaceLevel(iLevel)

    'このレベルを処理する。

    Set DDLevel = Nothing
Next

チェーンの各サーフェスにビットマップ データをロードするために、アプリケーションではミップマップ チェーンを手動でトラバースする必要がある。通常、この理由からチェーンをトラバースする。アプリケーションは、Direct3DBaseTexture8.GetLevelCount を呼び出して、ミップマップ テクスチャに格納されているレベルの数を取得できる。


テクスチャ ラッピング

ここでは、3D プリミティブへのテクスチャ ラッピングについて説明する。説明するトピックは、次のとおりである。

  • テクスチャ ラッピングとは
  • テクスチャ ラッピングの使い方

注 テクスチャ ラッピングと、類似した名前のテクスチャ アドレッシング モードを混同しないこと。詳細については、「テクスチャ アドレッシング モードとテクスチャ ラッピング」および「テクスチャ アドレッシング モード」を参照すること。


テクスチャ ラッピングとは

簡単に言えば、テクスチャ ラッピングとは、Microsoft® Direct3D® で各頂点に対して指定されたテクスチャ座標を使用して、テクスチャ処理したポリゴンをラスタ化する際の基本的な方法を変更する処理である。ポリゴンのラスタ化中に、システムはポリゴンの各頂点のテクスチャ座標の間を補間して、ポリゴンのすべてのピクセルに使用するテクセルを決める。通常、システムはテクスチャを 2D 平面として扱い、テクスチャ内のポイント A から ポイント B までの最短経路をとることで新しいテクセルを補間する。ポイント A が u, v 位置座標 (0.8, 0,1) で、ポイント B が (0.1,.9) の場合、補間の線は次の図のようになる。

上の図では、AB 間の最短距離がテクスチャのほぼ中央を通っている。u または v のテクスチャ座標のラッピングを有効にすると、u および v 方向でのテクスチャ座標間の最短経路を Direct3D が認識する方法が変化する。定義では、0.0 と 1.0 が同じ位置座標を占めると仮定して、テクスチャ ラッピングによってラスタライザがテクスチャ座標間の最短経路をとる。最後のビットは扱いにくいが、次のように考えるとわかりやすい。一方向のテクスチャ ラッピングを有効にすると、システムはテクスチャがあたかも円柱の周囲に巻き付いているかのようにテクスチャを扱う。たとえば、次の図を考える。

上の図は、u 方向のラッピングによって、システムによるテクスチャ座標の補間方法がどのように変化するかを示している。この例で使用した同じ点を、正常なまたは巻き付けていないテクスチャに使用すると、点 A と B の最短距離がテクスチャの中心にないことがわかる。この場合、最短距離は 0.0 と 1.0 が共に位置する境界を通っている。v 方向のラッピングも同様である。ただし、側面が下になっている円柱の周囲にテクスチャが巻き付いている。u および v の両方向のラッピングの場合はさらに複雑である。この場合は円環、つまりドーナツを想像するとよい。

テクスチャ ラッピングを実際に使用した最も一般的なアプリケーションは、環境マッピングの実行である。通常、環境マッピングでテクスチャ処理したオブジェクトは非常に反射的であり、シーンのオブジェクトの周囲に画像が反映する。これを説明するため、四方が壁で囲まれた部屋を考える。壁にはそれぞれ R、G、B、および Y という文字が付けてあり、それに対応する赤色、緑色、青色、および黄色で塗られている。このような単純な部屋の環境マッピングであれば、次のようになる。

この部屋の天井が、4 面からなる非常に反射しやすい柱で支えられているとする。この柱に環境マッピングを実行するのは非常に簡単である。しかし、壁の文字と色が柱に反射しているように見せるのは簡単なことではない。次の図は、上方の頂点の近くのテクスチャ座標を適用した、柱のワイヤ フレームを示している。ラッピングがこのテクスチャのエッジを横切る「継ぎ目」は、点線で示す。

u 方向でラッピングが有効になっているので、テクスチャ処理した柱には、環境マッピングからの色とシンボルが正しく表示されており、テクスチャの前面の継ぎ目では、ラスタライザがテクスチャ座標間の最短経路を正しく選択している (u 座標 0.0 と 1.0 が同じ位置を占めるという前提)。テクスチャを適用した柱は、次の図に示すようになる。

テクスチャ ラッピングが有効でない場合、ラスタライザは、実物のように反射した画像を生成するために必要な方向に補間を行わない。逆に、柱の前面部分では、u 座標の 0.175 および 0.875 間のテクセルが、テクスチャの中心を通るときに水平方向で圧縮され、ラップ エフェクトは崩れる。


テクスチャ ラッピングの使い方

テクスチャ ラッピングを有効にするには、次のサンプル コードに示すように、Direct3DDevice8.SetRenderState メソッドを呼び出す。

m_D3D.SetRenderState(D3DRS_WRAP0, D3DWRAPCOORD_0)

SetRenderState が受け取る第 1 パラメータは、設定するレンダリング ステートである。ラッピングを設定するテクスチャ レベルを指定する D3DRS_WRAP0 ～ D3DRS_WRAP7 の列挙値のいずれかを指定する。第 2 パラメータに D3DWRAPCOORD_0 ～ D3DWRAPCOORD_3 フラグを指定して、対応する方向のテクスチャ ラッピングを有効にするか、これらのフラグを組み合わせて複数の方向のラッピングを有効にする。フラグを省略すると、対応する方向でのテクスチャ ラッピングが無効になる。テクスチャ座標のセットに対してテクスチャ ラッピングを無効にするには、対応するレンダリング ステートの値を 0 に設定する。


テクスチャ ブレンディング

Microsoft® Direct3D® では、テクスチャをプリミティブの色とブレンドして透明エフェクトを生成できる。また、複数のテクスチャを 1 つのプリミティブにブレンドすることもできる。ここでは、テクスチャ ブレンディングの実行方法について説明する。説明するトピックは、次のとおりである。

  • アルファ テクスチャ ブレンディング
  • マルチパス テクスチャ ブレンディング
  • マルチ テクスチャ ブレンディング
  • テクスチャによるライト マッピング

テクスチャ ブレンディングを使用する場合、Microsoft® Visual Basic® アプリケーションでユーザーのハードウェアがテクスチャ ブレンディングをサポートしているかどうかを最初に調べる必要がある。この情報は、D3DCAPS8 型の TextureCaps メンバに保持されている。テクスチャ ブレンディング機能についてユーザーのハードウェアに問い合わせる方法の詳細については、「Direct3DDevice8.GetDeviceCaps」を参照すること。


アルファ テクスチャ ブレンディング

Microsoft® Direct3D® では、プリミティブをレンダリングするとき、プリミティブのマテリアルまたはその頂点の色、およびライティング情報に基づいてプリミティブの色を生成する。詳細については、「ライティングとマテリアルの概要」を参照すること。アプリケーションでテクスチャ ブレンディングが有効になっている場合、Direct3D は処理されたポリゴンのピクセル カラーの値を、既にフレーム バッファに格納されているピクセルと組み合わせなければならない。Direct3D では、次の公式を使用して、プリミティブの画像の各ピクセルに対する最終色を決める。

FinalColor = TexelColor × SourceBlendFactor + PixelColor × DestBlendFactor

この公式で、FinalColor は、ターゲット レンダリング サーフェスに出力される最後のピクセル カラーである。TexelColor は、カレント ピクセルに対応する入力カラー値 (テクスチャ フィルタリング後) を表す。Direct3D でテクセルをピクセルにマッピングする方法の詳細については、「テクスチャ フィルタリング」を参照すること。SourceBlendFactor は、最後に適用する入力カラー値の割合を決めるために Direct3D が使用する計算値である。PixelColor は、プリミティブの画像内に現在格納されているピクセルの色である。DestBlendFactor は、最後にレンダリングされるピクセルで使用されるカレント ピクセルの色の割合を表す。SourceBlendFactor と DestBlendFactor の値は、0.0 と 1.0 を含む 0.0 ～ 1.0 である。

上の公式からわかるように、SourceBlendFactor が D3DBLEND_ONE で DestBlendFactor が D3DBLEND_ZERO の場合、最後にレンダリングされるピクセルは透明度がないものとしてレンダリングされる。SourceBlendFactor が D3DBLEND_ZERO で DestBlendFactor が D3DBLEND_ONE の場合は、テクスチャは完全に透明になる。これらの係数に上記以外の値を設定した場合は、最後にレンダリングされるピクセルはある程度の透明性のある色とブレンドされる。

テクスチャ フィルタリング後は、すべてのピクセル カラー値は、赤色、緑色、および青色のカラー値を持っている。デフォルトでは、Direct3D は D3DBLEND_SRCALPHA を SourceBlendFactor として、D3DBLEND_INVSRCALPHA を DestBlendFactor として使用する。したがって、アプリケーションでは、テクスチャのアルファ値を設定することで処理されたピクセルの透明度を制御できる。

Visual Basic アプリケーションでは、D3DRS_SRCBLEND および D3DRS_DESTBLEND レンダリング ステートを使用してブレンディング係数を制御する。Direct3DDevice8.SetRenderState メソッドを呼び出して、第 1 パラメータの値としてレンダリング ステート値のいずれかを渡す。第 2 パラメータは、CONST_D3DBLEND 列挙のメンバでなければならない。


マルチパス テクスチャ ブレンディング

Microsoft® Direct3D® アプリケーションでは、マルチ レンダリング パスでプリミティブに各種テクスチャを適用して、数多くの特殊効果を実現できる。この処理は一般にマルチパス テクスチャ ブレンディングと呼ばれる。マルチパス テクスチャ ブレンディングの一般的な用途は、いくつかの異なるテクスチャから複数の色を適用して、複雑なライティングおよびシェーディング モデルのエフェクトをエミュレートすることである。これをライト マッピングと呼ぶ。詳細については、「テクスチャによるライト マッピング」を参照すること。

注 デバイスによっては、単一のパスで、複数のテクスチャをプリミティブに適用できる場合もある。詳細については、「マルチ テクスチャ ブレンディング」を参照すること。

ユーザーのハードウェアでマルチ テクスチャ ブレンディングがサポートされていない場合でも、アプリケーションでは、マルチパス テクスチャ ブレンディングを使用して同じ視覚エフェクトを実現できる。ただし、マルチ テクスチャ ブレンディングを使用した場合には、アプリケーションは可能なフレーム レートを維持できない。

Visual Basic アプリケーションでマルチ テクスチャ ブレンディングを実行するには

  1. Direct3DDevice8.SetTexture メソッドを呼び出して、テクスチャ ステージ 0 にテクスチャを設定する。
  2. Direct3DDevice8.SetTextureStageState メソッドを使用して、目的の色およびアルファ ブレンディング引数と処理を選択する。マルチパス テクスチャ ブレンディング用の最適な設定はデフォルト設定である。
  3. シーン内の適切なオブジェクトをレンダリングする。
  4. 次のテクスチャをテクスチャ ステージ 0 に設定する。
  5. D3DRS_SRCBLEND および D3DRS_DESTBLEND レンダリング ステートを設定して、ブレンド元およびブレンド先のブレンディング係数を必要に応じて調整する。これらのパラメータに基づいて、新しいテクスチャがレンダリング ターゲット サーフェス内の既存のピクセルでブレンドされる。
  6. 必要に応じて、ほかのテクスチャに対して手順 3、4、および 5 を繰り返す。


マルチ テクスチャ ブレンディング

Microsoft® Direct3D® では、単一のパスで、最大 8 つのテクスチャをプリミティブにブレンドできる。マルチ テクスチャ ブレンディングを使用すれば、Direct3D アプリケーションのフレーム レートを大幅に上げることができる。アプリケーションは、マルチ テクスチャ ブレンディングを採用して、テクスチャ、影、スペキュラ ライト、ディフューズ ライトなどの特殊効果を単一パスで適用できる。

マルチ テクスチャをブレンドするには、アプリケーションでそれらのテクスチャをカレント テクスチャ セットに割り当て、次にブレンディング ステージを作成する。以下のトピックでは、これらの手順の実行方法について説明する。

  • テクスチャ ステージとテクスチャ ブレンディング カスケード
  • テクスチャ ブレンディング処理と引数
  • カレント テクスチャの割り当て
  • ブレンディング ステージの作成


テクスチャ ステージとテクスチャ ブレンディング カスケード

Microsoft® Direct3D® は、テクスチャ ステージを使用して、シングルパスのマルチ テクスチャ ブレンディングをサポートしている。テクスチャ ステージには 2 つの引数を受け取り、ブレンディング処理を行い、後続の処理またはラスタ化に結果を渡す。テクスチャ ステージは、次の図のように図式化できる。

上の図に示すように、テクスチャ ステージは指定のオペレータを使用して 2 つの引数をブレンドする。一般的な操作には、引数の色またはアルファ要素の単純変調や加算があるが、20 以上の操作がサポートされている。ステージの引数は、関連付けられたテクスチャ、補間色または補間アルファ (グーロー シェーディング中の補間)、任意の色とアルファ、または以前のテクスチャ ステージからの結果である。詳細については、「テクスチャ ブレンディング処理と引数」を参照すること。

注 Direct3D では、カラー ブレンディングとアルファ ブレンディングを区別する。アプリケーションでは、色とアルファに対して個別にブレンディング処理と引数を設定し、これらの設定が互いの結果に影響することはない。

マルチ ブレンディング ステージで使用される引数と処理の組み合わせは、単純なフローを基本とするブレンディング言語を定義する。1 つのステージの結果は別のステージに流れ、次にそのステージの結果が次のステージに流れ、以下同様に続く。ステージからステージへの流れが最終的にポリゴン上でラスタ化される概念を、通常、テクスチャ ブレンディング カスケードと呼ぶ。次の図は、個別のテクスチャ ステージがどのようにテクスチャ ブレンディング カスケードを構成するかを示している。

デバイス内の各ステージは、0 から始まるインデックスを持つ。Direct3D では、最大 8 つのブレンディング ステージを利用できる。ただし、現在のハードウェアでサポートされるステージ数を判断するために、デバイス機能を調べる必要がある。第 1 ブレンディング ステージはインデックス 0 にあり、第 2 ステージはインデックス 1 にあり、以下インデックス 7 まで同様である。システムは、インデックスの昇順にステージをブレンドする。

必要な数だけのステージを使用する。使用しないブレンディング ステージはデフォルトで無効になる。アプリケーションが最初の 2 つのステージだけを使用する場合は、ステージ 0 と 1 についてだけ設定操作と引数が必要である。システムは 2 つのステージをブレンドし、無効なステージを無視する。

最適化に関する注意 オブジェクトによっては 4 つのステージを使用したり、2 つのステージを使用するなど、状況に応じてアプリケーションで使用するステージの数が変わる場合は、以前に使用したすべてのステージを明示的に無効にしなくてもよい。最初の未使用のステージに対してカラー処理を無効にしても、それよりインデックスが大きいステージでは無効にならない。カラー処理を最初のテクスチャ ステージ (ステージ 0) に設定すると、すべてのテクスチャ マッピングを無効にできる。


テクスチャ ブレンディング処理と引数

アプリケーションでは、ブレンディング ステージをカレント テクスチャ セットの各テクスチャに関連付ける。「テクスチャ ステージとテクスチャ ブレンディング カスケード」で説明するように、Microsoft® Direct3D® では、セットの最初のテクスチャから順に 8 番目のテクスチャまで各ブレンディング ステージを評価する。

Direct3D では、カレント テクスチャ セットの各テクスチャの情報を、関連付けられているブレンディング ステージに適用する。アプリケーションでは、Direct3DDevice8.SetTextureStageState を呼び出して、テクスチャ ステージからどの情報を使用するかを制御する。カラー チャネルとアルファ チャネルの処理は、個別に設定することができる。各処理では 2 つの引数を使用する。カラー チャネル処理を指定するには、D3DTSS_COLOROP ステージ ステートを使用し、アルファ処理を指定するには、D3DTSS_ALPHAOP ステージ ステートを使用する。これらのステージ ステートは共に CONST_D3DTEXTUREOP 列挙型からの値を使用する。

テクスチャ ブレンディング引数には、CONST_D3DTEXTURESTAGESTATETYPE 列挙の D3DTSS_COLORARG1、D3DTSS_COLORARG2、D3DTSS_ALPHARG1、および D3DTSS_ALPHARG2 メンバを使用する。対応する引数は、テクスチャ引数フラグを使用して識別する。

注 あるテクスチャ ステージのカラー処理を D3DTOP_DISABLE に設定することで、そのテクスチャ ステージと、それに続くカスケード内のテクスチャ ブレンディング ステージを無効にすることができる。カラー処理を無効すると、アルファ処理も同様に無効になる。カラー処理が有効のときに、アルファ処理を無効にすることはできない。カラー ブレンディングが有効のときにアルファ処理を D3DTOP_DISABLE に設定すると、その動作は不定である。

デバイスでサポートされているテクスチャ ブレンディング処理を調べるには、D3DCAPS8 型の TextureCaps メンバに問い合わせる。


カレント テクスチャの割り当て

Microsoft® Direct3D® は、最大 8 つのカレント テクスチャによるリストを利用できる。Direct3D では、レンダリングするすべてのプリミティブに、これらのテクスチャをブレンドする。テクスチャ インターフェイス ポインタとして作成したテクスチャのみ、カレント テクスチャ セットで使用できる。

Microsoft® Visual Basic® で記述されたアプリケーションでは、Direct3DDevice8.SetTexture を呼び出して、カレント テクスチャ セットにテクスチャを割り当てる。第 1 パラメータは、0 ～ 7 の範囲の数値でなければならない。第 2 パラメータとして、テクスチャ インターフェイス ポインタを渡す。

次の Visual Basic コードは、テクスチャをカレント テクスチャ セットに割り当てる方法を示している。

' このコード例で、変数 d3dDevice は
' Direct3DDevice8 オブジェクトへの有効な参照であり
' d3dTexture は Direct3DBaseTexture8 オブジェクトへの有効な参照であると仮定している。

' 3 番目のテクスチャを設定する。
Call d3dDevice.SetTexture(2, d3dTexture)

注 ソフトウェア デバイスでは、テクスチャを一度に複数のテクスチャ ステージに割り当てることはできない。


ブレンディング ステージの作成

ブレンディング ステージとは、テクスチャのブレンディング方法を定義する、一連のテクスチャ処理と引数である。ブレンディング ステージを作成するとき、Microsoft® Visual Basic® アプリケーションでは Direct3DDevice8.SetTextureStageState メソッドを呼び出す。最初の呼び出しは、実行する処理を指定する。さらに 2 回の呼び出しを行って、処理を適用する引数を定義する。次のサンプル コードは、ブレンディング ステージの作成方法を示している。

' この例では、d3dDevice は Direct3DDevice8 オブジェクトへの
' 有効な参照であると仮定している。

' 最初のテクスチャのカラー処理を設定する。
Call d3dDevice.SetTextureStageState(0, D3DTSS_COLOROP, D3DTOP_ADD)

' 引数 1 をテクスチャ カラーに設定する。
Call d3dDevice.SetTextureStageState(0, D3DTSS_COLORARG1, D3DTA_TEXTURE)

' 引数 2 を補間するディフューズ色に設定する。
Call d3dDevice.SetTextureStageState(0, D3DTSS_COLORARG2, D3DTA_DIFFUSE)

テクスチャのテクセル データには、カラー値とアルファ値が含まれる。アプリケーションでは、単一のブレンディング ステージでカラー値とアルファ値の両方を定義できる。カラー処理とアルファ処理には、それぞれ独自の引数がある。詳細については、「CONST_D3DTEXTURESTAGESTATETYPE」を参照すること。


テクスチャによるライト マッピング

3D シーンをリアルにレンダリングするには、光源がシーンの表示に与えるエフェクトを考慮しなければならない。フラット シェーディングやグーロー シェーディングなどの技術はこの点で貴重なツールであるが、これらの技術だけでは不十分である。Microsoft® Direct3D® は、マルチパスのマルチ テクスチャ ブレンディングをサポートしている。これらの能力を使用することで、シェーディング手法だけでレンダリングするよりも、よりリアルなシーンをレンダリングできる。1 つまたは複数のライト マップを利用すれば、プリミティブにライティングと影の領域をマップできる。

ライト マップとは、3D シーンのライティングについての情報を含むテクスチャまたはテクスチャ グループのことである。このライティング情報をライト マップのアルファ値、カラー値、またはその両方に格納できる。

マルチパス テクスチャ ブレンディングを使用してライト マッピングを実現する場合は、最初のパスでプリミティブにライト マップをレンダリングする必要がある。また、第 2 のパスを使用して、ベース テクスチャをレンダリングする必要がある。ただし、スペキュラ ライト マッピングは除く。スペキュラ ライト マップの場合は、最初にベース テクスチャをレンダリングし、次にライト マップを追加する。

マルチ テクスチャ ブレンディングによって、1 つのパスでライト マップとベース テクスチャをレンダリングできる。ユーザーのハードウェアでマルチ テクスチャ ブレンディングがサポートされている場合は、ライト マッピングを行うときにこのブレンディングを利用するようにする。これにより、アプリケーションのパフォーマンスが大幅に向上する。

ライト マップを使用すれば、Direct3D アプリケーションでは、プリミティブをレンダリングするときにさまざまなライティング エフェクトを生成できる。モノクロ ライティングやカラー ライティングをシーンにマッピングできるほか、スペキュラ ハイライトやディフューズ ライトなどの細かなエフェクトも追加できる。

Direct3D テクスチャ ブレンディングを使用してライト マッピングを実行する方法については、以下のトピックで説明する。

  • モノクロ ライト マップ
  • カラー ライティング マップ
  • スペキュラ ライト マップ
  • ディフューズ ライト マップ


モノクロ ライト マップ

一部の古い 3D アクセラレータ ボードでは、転送先ピクセルのアルファ値を使用するテクスチャ ブレンディングをサポートしていない場合がある。詳細については、「アルファ テクスチャ ブレンディング」を参照すること。これらのアダプタでは、一般にマルチ テクスチャ ブレンディングもサポートしていない。このようなアダプタでアプリケーションを実行する場合は、マルチパス テクスチャ ブレンディングを使用してモノクロ ライト マッピングを実行できる。

モノクロ ライト マッピングを実行するには、アプリケーションでライティング情報をライト マップ テクスチャのアルファ データに格納する。アプリケーションは、Microsoft® Direct3D® のテクスチャ フィルタリング能力を使用して、プリミティブの画像の各ピクセルからライト マップの対応するテクセルへのマッピングを実行する。プログラムで、転送元ブレンディング係数を対応するテクセルのアルファ値に設定する。

次の Microsoft® Visual Basic® コードは、アプリケーションでテクスチャをモノクロ ライト マップとして使用する方法を示している。

' この例では、D3DDevice は Direct3DDevice8 オブジェクトへの有効な参照であり、
' texLightMap はモノクロ ライト マップ データを含む Direct3DTexture8 オブジェクトへの
' 有効な参照であると仮定している。

' ライト マップ テクスチャをカレント テクスチャとして設定する。
Call D3DDevice.SetTexture(0, texLightMap)

' カラー処理を設定する。
Call D3DDevice.SetTextureStageState(0, D3DTSS_COLOROP, D3DTOP_SELECTARG1)

' 引数 1 をカラー処理に設定する。
Call D3DDevice.SetTextureStageState(0, D3DTSS_COLORARG1, _
 D3DTA_TEXTURE Or D3DTA_ALPHAREPLICATE)

転送先アルファ ブレンディングをサポートしていないディスプレイ アダプタは、通常マルチ テクスチャ ブレンディングをサポートしていないので、この例では、すべての 3D アクセラレータ カードで使用できるライト マップを最初のテクスチャとして設定している。また、この例では、テクスチャのブレンディング ステージに対するカラー処理を設定して、テクスチャ データをプリミティブの既存の色とブレンドしている。その次に、入力データとして最初のテクスチャとプリミティブの既存の色を選択している。


カラー ライティング マップ

一般に、カラー ライティング マップを使用すれば、3D シーンをよりリアルにレンダリングできる。カラー ライティング マップは、ライティング情報としてライト マップのRGB データを使用する。

次の Microsoft® Visual Basic® コードは、RGB カラー データを使用したライト マッピングを示している。

' この例では、D3DDevice は Direct3DDevice8 オブジェクトへの有効な参照であり、
' texLightMap は RGB ライト マップ データを含む 3DBaseTexture8 オブジェクトへの
' 有効な参照であると仮定している。

' ライト マップ テクスチャを最初のテクスチャとして設定する。
D3DDevice.SetTexture 0, texLightMap

D3DDevice.SetTextureStageState 0, D3DTSS_COLOROP, D3DTOP_MODULATE
D3DDevice.SetTextureStageState 0, D3DTSS_COLORARG1, D3DTA_TEXTURE
D3DDevice.SetTextureStageState 0, D3DTSS_COLORARG2, D3DTA_DIFFUSE

この例では、ライト マップを最初のテクスチャとして設定している。その次に、最初のブレンディング ステージのステートを設定して、入力テクスチャ データを乗算している。また、最初のテクスチャとプリミティブのカレント カラーを乗算処理用の引数として使用している。


スペキュラ ライト マップ

光源で照らしたときに輝くオブジェクト (反射性の高いマテリアルを使用するオブジェクト) は、スペキュラ ハイライトを受け取る。場合によっては、ライティング モジュールで生成されたスペキュラ ハイライトは正確でない場合もある。より効果的なハイライトを生成するために、多くの Microsoft® Direct3D® アプリケーションではプリミティブにスペキュラ ライト マップを適用する。

スペキュラ ライト マッピングを実行するには、まずスペキュラ ライト マップをプリミティブの既存のテクスチャに合わせて乗算する。次に、モノクロまたは RGB ライト マップを追加する。

次のコードは、Microsoft® Visual Basic® でこの処理を実行する例を示している。

' この例では、d3dDevice は Direct3DDevice8 オブジェクトへの
' 有効な参照であると仮定している。
' texBaseTexture は、テクスチャへの有効な参照である。
' texSpecLightMap は、RGB スペキュラ ライト マップ データを含む
' テクスチャへの有効な参照である。
' texLightMap は、RGB ライト マップ データを含む
' テクスチャへの有効な参照である。

' ベース テクスチャを設定する。
Call d3dDevice.SetTexture(0, texBaseTexture)

' ベース テクスチャ処理と引数を設定する。
Call d3dDevice.SetTextureStageState(0, D3DTSS_COLOROP, D3DTOP_MODULATE)
Call d3dDevice.SetTextureStageState(0, D3DTSS_COLORARG1, D3DTA_TEXTURE)
Call d3dDevice.SetTextureStageState(0, D3DTSS_COLORARG2, D3DTA_DIFFUSE)

' スペキュラ ライト マップを設定する。
Call d3dDevice.SetTexture(1, texSpecLightMap)

' スペキュラ ライト マップ処理と引数を設定する。
Call d3dDevice.SetTextureStageState(1, D3DTSS_COLOROP, D3DTOP_ADD)
Call d3dDevice.SetTextureStageState(1, D3DTSS_COLORARG1, D3DTA_TEXTURE)
Call d3dDevice.SetTextureStageState(1, D3DTSS_COLORARG2, D3DTA_CURRENT)

' RGB ライト マップを設定する。
Call d3dDevice.SetTexture(2, texLightMap)

' RGB ライト マップ処理と引数を設定する。
Call d3dDevice.SetTextureStageState(2, D3DTSS_COLOROP, D3DTOP_MODULATE)
Call d3dDevice.SetTextureStageState(2, D3DTSS_COLORARG1, D3DTA_TEXTURE)
Call d3dDevice.SetTextureStageState(2, D3DTSS_COLORARG2, D3DTA_CURRENT)


ディフューズ ライト マップ

光源で照らしたとき、光沢のないサーフェスはディフューズ ライトを放つ。ディフューズ ライトの輝きは、光源からの距離、およびサーフェス法線と光源の方向ベクトルとの角度によって異なる。ライティング計算によってシミュレートするディフューズ ライトのエフェクトは一般的なものである。

テクスチャ ライト マップを使用してディフューズ ライトをシミュレートできる。これを行うには、次の Microsoft® Visual Basic® コードで示すように、ディフューズ ライト マップをベース テクスチャに追加する。

' この例で、d3dDevice は Direct3DDevice8 オブジェクトへの
' 有効な参照であると仮定している。
' texBaseTexture は、テクスチャへの有効な参照である。
' texDiffuseLightMap は、RGB ディフューズ ライト マップ データを含む
' テクスチャへの有効な参照である。

' ベース テクスチャを設定する。
Call d3dDevice.SetTexture(0, texBaseTexture)

' ベース テクスチャ処理と引数を設定する。
Call d3dDevice.SetTextureStageState(0, D3DTSS_COLOROP, D3DTOP_MODULATE)
Call d3dDevice.SetTextureStageState(0, D3DTSS_COLORARG1, D3DTA_TEXTURE)
Call d3dDevice.SetTextureStageState(0, D3DTSS_COLORARG2, D3DTA_DIFFUSE)

' ディフューズ ライト マップを設定する。
Call d3dDevice.SetTexture(1, texDiffuseLightMap)

' ブレンディング ステージを設定する。
Call d3dDevice.SetTextureStageState(1, D3DTSS_COLOROP, D3DTOP_MODULATE)
Call d3dDevice.SetTextureStageState(1, D3DTSS_COLORARG1, D3DTA_TEXTURE)
Call d3dDevice.SetTextureStageState(1, D3DTSS_COLORARG2, D3DTA_CURRENT)


圧縮したテクスチャ リソース

Microsoft® Direct3D® は、3D モデルのテクスチャ処理に使用するサーフェス圧縮機能を備えている。ここでは、圧縮テクスチャ サーフェスのデータの作成および操作について説明する。

説明するトピックは、次のとおりである。

  • 圧縮したテクスチャとは
  • 圧縮したテクスチャ フォーマット
  • 圧縮したテクスチャの使い方


圧縮したテクスチャとは

テクスチャ マップとは、3D の形状の上に描画して細部を加えるデジタル画像のことである。テクスチャ マップは、ラスタ化の実行中にこのような形状にマッピングされる。このプロセスは、システム バスとメモリの両方を大量に使用する場合がある。テクスチャで消費されるメモリ容量を減らすために、Microsoft® Direct3D® ではテクスチャ サーフェスの圧縮をサポートしている。いくつかの Direct3D デバイスは、圧縮したテクスチャ サーフェスをネイティブにサポートする。このようなデバイスで圧縮したサーフェスを作成し、そのデバイスにデータをロードしてしまえば、ほかのテクスチャ サーフェスと同様に Direct3D でサーフェスを使用できる。テクスチャが 3D サーフェス オブジェクトにマップされる場合、Direct3D は圧縮の復元を処理する。


圧縮したテクスチャ フォーマット

ここでは、圧縮したテクスチャ フォーマットの内部組織について説明する。圧縮フォーマット間の変換には D3DX 関数を使用するため、これらの情報を詳しく知る必要はない。ただし、圧縮したサーフェス データを直接処理する場合は、この情報が役立つ。

Direct3D では、テクスチャ マップを 4 × 4 のテクセル ブロックに分割するために圧縮フォーマットを使用する。テクスチャに透過性が含まれない場合 (不透明)、または透過性が 1 ビット アルファで指定される場合、8 バイト ブロックがテクスチャ マップ ブロックを表す。テクスチャ マップに透過型テクセルが含まれない場合、アルファ チャネルを使用して 16 バイト ブロックがテクスチャ マップ ブロックを表す。

  • 不透明と 1 ビット アルファ テクスチャ
  • アルファ チャネルによるテクスチャ
  • ストレージの効率とテクスチャ圧縮について
  • 単一テクスチャ内でのフォーマットの組み合わせ

注 あらゆる単一のテクスチャでは、16 テクセルのグループごとに 64 ビットまたは 128 ビットとして格納されるデータを指定しなくてはならない。64 ビット ブロック (つまり、フォーマット DXT1) がテクスチャ用に使用される場合、いくつかのテクスチャのブロックごとに不透明と 1 ビット アルファ フォーマットを組み合わせることができる。つまり、色 0 と色 1 の符号なし整数のマグニチュードの比較は、16 テクセルの各ブロックごとに実行される。

128 ビット ブロックを使用する場合、テクスチャ全体にアルファ チャネルを明示的 (フォーマット DXT2 または DXT3) に、または補間したモード (フォーマット DXT4 または DXT5) で指定しなくてはならない。色の場合と同様、補間したモードを選択すると、8 つの補間したアルファか、ブロック単位で使用できる 6 つの補間したアルファ モードのいずれかを使用できる。さらに、アルファ 0 とアルファ 1 の大きさの比較は、ブロックごとに行われる。

DXTn フォーマットのピッチは、DirectX 7 で返されていたものとは異なっている。今後は、ブロック 1 行のピッチのことである。たとえば、幅が 16 とすると、ピッチは 4 ブロック (DXT1 は 4*8、DXT2 ～ 5 は 4*16) となる。


不透明と 1 ビット アルファ テクスチャ

テクスチャ フォーマット DXT1 は、不透明または単一の透過型色のあるテクスチャ用である。

各不透明または 1 ビット アルファ ブロックのために、2 つの 16 ビット値 (RGB 5:6:5 フォーマット) とピクセル単位の 2 ビットの 4 × 4 ビットマップが格納される。これは、16 テクセルに対して合計 64 ビット、つまり 4 ビット/テクセルとなる。ブロック ビットマップには、4 色間を選択するテクセルごとに 2 ビットがある。4 色のうち 2 色は、符号化されたデータに格納される。ほかの 2 色は、線形補間で格納される色から派生する。次の図は、このレイアウトを示している。

1 ビット アルファ フォーマットは、ブロックに格納される 16 ビットカラー値を比較することにより、不透明フォーマットと区別される。これらは、符号なしの整数として処理される。最初の色が次の色よりも大きい場合は、不透明テクセルだけが定義されていることを意味する。つまり、テクセルを表すのに 4 色が使用される。4 色の符号化には 2 つの派生した色があり、全 4 色は RGB 色空間に等しく配布される。このフォーマットは、RGB 5:6:5 フォーマットに類似している。ほかの点では、1 ビット アルファ透過性用にこれらの色は使用され、4 番目の色は透過型テクセルを表すために確保される。

3 つの色の符号化には 1 つの派生した色があり、4 番目の 2 ビット コードは透過型テクセル (アルファ情報) を含むために確保される。このフォーマットは、アルファ マスクを符号化するために使用される最後のビットのある RGBA 5:5:5:1 に類似している。

8 バイト ブロック用のメモリ層を次の表に示す。最初のインデックスが y 軸、2 番目のインデックスが x 軸に対応すると考える。たとえば、テクセル [1][2] は (x,y) = (2,1) でテクスチャ マップ ピクセルを参照する。

次の表は、8 バイト (64 ビット) ブロック用のメモリ レイアウトを示している。

単語アドレス | 16 ビット単語
0 | 色 _0
1 | 色 _1
2 | ビットマップ単語 _0
3 | ビットマップ単語 _1

色 0 と色 1 (2 極値での色) の配置を次に示す。

ビット | 色
04:00 (LSB) | 青色成分
10:5 | 緑色成分
15:11 | 赤色成分

ビットマップ word_0 の配置

ビット | テクセル
01:00 (LSB) | テクセル [0][0]
3:2 | テクセル [0][1]
5:4 | テクセル [0][2]
7:6 | テクセル [0][3]
9:8 | テクセル [1][0]
11:10 | テクセル [1][1]
13:12 | テクセル [1][2]
15:14 (MSB) | テクセル [1][3]

ビットマップ word_1 の配置

ビット | テクセル
01:00 (LSB) | テクセル [2][0]
3:2 | テクセル [2][1]
5:4 | テクセル [2][2]
7:6 | テクセル [2][3]
9:8 | テクセル [3][0]
11:10 | テクセル [3][1]
13:12 | テクセル [3][2]
15:14 (MSB) | テクセル [3][3]

不透明色符号の例

不透明符号の例として、赤と黒が極値であると仮定する。赤は色 _0、黒は色 _1 とする。一様に傾度を互いに分割したフォームの補間した 4 色がある。4 × 4 ビットマップの値を決定するには、次に示す計算式を使用する。

00 ? color_0
01 ? color_1
10 ? 2/3 color_0 + 1/3 color_1
11 ? 1/3 color_0 + 2/3 color_1

このビットマップは、次のようになる。

このビットマップは次のような一連の色となる。

1 ビット アルファ符号の例

符号なし 16 ビット整数 (色 _0) が符号なし 16 ビット整数 (色 _1) より小さい場合、このフォーマットが選択される。このフォーマットは、青空を背景にした木の葉などに使用できる。いくつかのテクセルは、3 色の緑の影が葉に対して使用される間に透過型として記される。これら 2 色は極値に適合し、3 番目の色は補間した色となる。

そのような画像の例を次に示す。

上の図で、白色で示す画像では、テクセルは透過型として符号化されることに注意すること。また、透過型テクセルの RGBA コンポーネントは、ブレンディング前にゼロに設定するよう注意すること。

色と透過性に対するビットマップ符号は、次の計算式を使用して決定される。

00 ? color_0
01 ? color_1
10 ? 1/2 color_0 + 1/2 color_1
11   ?   Transparent

ビットマップは、次のようになる。


アルファ チャネルによるテクスチャ

より複雑な透過性を示すテクスチャ マップの符号化には、2 とおりの方法がある。どちらの場合も、透過性を記述するブロックは既に記述されている 64 ビット ブロックより先に起こる。透過性はピクセル単位に 4 ビットの 4 × 4 ビットマップ (明示的な符号化)、またはそれ以下のビットのビットマップのどちらかであり、線形補間は色符号化で使用されることと類似する。

透過性ブロックと色ブロックの配置は、次の表に示すとおりである。

単語アドレス | 64 ビット ブロック
3:0 | 透過性ブロック
7:4 | 既に記述された 64 ビット ブロック

明示的なテクスチャ符号化

明示的なテクスチャ符号化 (DXT2 と DXT3 フォーマット) のために、透過性を記述するテクセルのアルファ成分は、テクセルごとに 4 ビットの 4 × 4 ビットマップで符号化される。これらの 4 ビットは、アルファ データで 4 つの最上位ビットをディザリングしたり、それらを単に使用するなど、さまざまな方法で達成できる。ただし、作成されると、あらゆる補間のフォームがないとそれだけでしか使用できない。

次の図は、64 ビットの透過性ブロックを示している。

注 Microsoft® Direct3D® の圧縮メソッドでは、4 つの最上位ビットを使用する。

次の表は、アルファ情報が各 16 ビット単語用に配置される方法について示している。

単語 0 用の配置は、次のとおりである。

ビット | アルファ
3:0 (LSB) | [0][0]
7:4 | [0][1]
11:8 | [0][2]
15:12 (MSB) | [0][3]

単語 1 用の配置は、次のとおりである。

ビット | アルファ
3:0 (LSB) | [1][0]
7:4 | [1][1]
11:8 | [1][2]
15:12 (MSB) | [1][3]

単語 2 用の配置は、次のとおりである。

ビット | アルファ
3:0 (LSB) | [2][0]
7:4 | [2][1]
11:8 | [2][2]
15:12 (MSB) | [2][3]

単語 3 用の配置は、次のとおりである。

ビット | アルファ
3:0 (LSB) | [3][0]
7:4 | [3][1]
11:8 | [3][2]
15:12 (MSB) | [3][3]

DXT2 と DXT3 の違いは、DXT2 フォーマットではカラー データはあらかじめアルファを掛けれられていることを前提としている。DXT3 フォーマットでは、カラー データはあらかじめアルファを掛けれられていないことを前提としている。これらの 2 つのフォーマットが必要とされる理由は、テクスチャが使用される大部分の場合、データをただ調べるだけではカラー値にアルファが掛かっているかどうかを判断できないからである。このような情報が実行時に必要なので、2 つの FOURCC コードを使用してこれらの場合を区別している。ただし、これらの 2 つのフォーマットに使用されるデータと補間のメソッドは同じである。

テクセルが透過型かどうかを判定するために DXT1 で使用される色比較は、このフォーマットでは使用されない。色比較なしでは、カラー データは常に 4 色モードとして処理されることを前提としている。つまり、DXT1 コードの先頭の if 文は次のようになる。

if ((color_0 > color_1) OR !DXT1) {

3 ビット線形アルファ補間

DXT4 および DXT5 フォーマットに対する透過性の符号は、色に使用される線形符号と類似する概念が基となる。2 つの 8 ビット アルファ値とピクセル単位に 3 ビットの 4 × 4 ビットマップは、ブロックの最初の 8 バイトに格納される。典型的なアルファ値は、中間アルファ値を補間するために使用される。追加情報は、2 つのアルファ値を格納する方法で利用できる。アルファ _0 がアルファ _1 より大きい場合、6 つの中間アルファ値が補間により作成される。また、4 つの中間アルファ値が指定されるアルファ極値間で補間される。2 つの追加の明示的なアルファ値は、0 (完全に透過型) と 255 (完全に不透明) となる。

アルファ ブロックのメモリ層を次に示す。

バイト | アルファ
0 | アルファ _0
1 | アルファ _1
2 | [0][2] (2 LSBs) , [0][1], [0][0]
3 | [1][1] (1 LSB) , [1][0], [0][3], [0][2] (1 MSB)
4 | [1][3], [1][2], [1][1] (2 MSBs)
5 | [2][2] (2 LSBs) , [2][1], [2][0]
6 | [3][1] (1 LSB) , [3][0], [2][3], [2][2] (1 MSB)
7 | [3][3], [3][2], [3][1] (2 MSBs)

DXT4 と DXT5 の違いは、DXT4 フォーマットではカラー データはあらかじめアルファを掛けれられていることを前提としている。DXT5 フォーマットでは、カラー データはあらかじめアルファを掛けれられていないことを前提としている。これらの 2 つのフォーマットが必要とされる理由は、テクスチャが使用される大部分の場合、データをただ調べるだけではカラー値にアルファが掛かっているかどうかを判断できないからである。このような情報が実行時に必要なので、2 つの FOURCC コードを使用してこれらの場合を区別している。ただし、これらの 2 つのフォーマットに使用されるデータと補間のメソッドは同じである。

テクセルが透過型かどうかを判定するために DXT1 で使用される色比較は、これらのフォーマットでは使用されない。色比較なしでは、カラー データは常に 4 色モードとして処理されることを前提としている。つまり、DXT1 コードの先頭の if 文は次のようになる。

if ((color_0 > color_1) OR !DXT1) {


ストレージの効率とテクスチャ圧縮について

すべてのテクスチャ圧縮フォーマットは、2 の累乗である。これは、テクスチャが必ずしも正方形であるということではないが、X と Y が両方とも 2 の累乗であるということである。たとえば、テクスチャが初めは 512 × 128 バイトだとすると、次のミップマップ処理では 256 × 64 というように、各レベルが 2 の累乗ずつ減っていく。さらにレベルが小さくなり、テクスチャが 16 × 2 および 8 × 1 までフィルタリング処理されると、不用ビットができる。これは、圧縮ブロックが常に 4 × 4 のテクセル ブロックだからである。ブロックの未使用部分はパディングされる。最小レベルでは不用ビットがあるものの、全体的に得られるものは依然として重要である。理論的に最悪の場合とは、2K × 1 テクスチャ (2 の 0 乗) である。この場合、1 ブロックにつき 1 ピクセル行だけしか符号化されず、ブロックの残りの部分は未使用となる。


単一テクスチャ内でのフォーマットの組み合わせ

重要な点は、あらゆる単一のテクスチャでは、16 テクセルのグループごとに 64 ビットまたは 128 ビットとして格納されるデータを指定するよう注意するという点である。64 ビット ブロック (つまり、フォーマット DXT1) がテクスチャ用に使用される場合、いくつかのテクスチャのブロックごとに不透明と 1 ビット アルファ フォーマットを組み合わせることができる。つまり、色 0 と色 1 の符号なし整数のマグニチュードの比較は、16 テクセルの各ブロックごとに実行される。

128 ビット ブロックを使用する場合、テクスチャ全体にアルファ チャネルを明示的 (フォーマット DXT2 または DXT3) に、または補間したモード (フォーマット DXT4 または DXT5) で指定しなくてはならない。色の場合と同様、補間したモード (フォーマット DXT4 および DXT5) を選択する場合、8 つの補間したアルファか、ブロック単位で使用できる 6 つの補間したアルファ モードのいずれかを使用できることに注意すること。さらに、アルファ 0 とアルファ 1 のマグニチュードの比較は、ブロックごとに行われる。


圧縮したテクスチャの使い方

ここでは、Microsoft® Direct3D® アプリケーションで圧縮したテクスチャを使用する方法について説明する。

説明するトピックは、次のとおりである。

  • 圧縮したテクスチャのサポートの判定
  • 圧縮したテクスチャの作成
  • 圧縮したテクスチャの復元


圧縮したテクスチャのサポートの判定

アプリケーションでレンダリング デバイスを作成する前に、Direct3D8.CheckDeviceFormat を呼び出して、圧縮テクスチャ サーフェスからのテクスチャ処理をデバイスがサポートするかどうかを調べることができる。このメソッドは、アダプタを表すデバイス上でサーフェス フォーマットがテクスチャとして使用できるかどうかを判定する。アダプタをテストするには、DXT1、DXT2、DXT3、DXT4、または DXT5 の FOURCC コードを使用するピクセル フォーマットのいずれかを指定する。CheckDeviceFormat が D3D_OK を返した場合、デバイスはそのフォーマットを使用する圧縮テクスチャ サーフェスから直接テクスチャを得ることができる。この場合、Direct3DDevice8.SetTexture メソッドを呼び出して、Microsoft®Direct3D® で圧縮テクスチャ サーフェスを直接使用できる。デバイスが圧縮テクスチャ サーフェスからのテクスチャ処理をサポートしない場合でも、テクスチャ データを圧縮フォーマット サーフェス内に格納できる。ただし、圧縮テクスチャをテクスチャとして使用する前に、サポートされるフォーマットに変換しなければならない。


圧縮したテクスチャの作成

アダプタで圧縮テクスチャ フォーマットをサポートできるデバイスを作成した後、圧縮テクスチャ リソースを作成できる。Direct3DDevice8.CreateTexture を呼び出して、Format パラメータに圧縮テクスチャ フォーマットを指定する。

テクスチャ オブジェクトに画像をロードする前に、Direct3DTexture8.GetSurfaceLevel メソッドを呼び出して、テクスチャ サーフェスへのポインタを取得する。

これで、D3DXLoadSurface で始まる D3DX 関数を使用して、GetSurfaceLevel で取得したサーフェスに画像をロードできる。これらの関数は、圧縮テクスチャ フォーマット間の変換を処理する。

SDK で提供される DXTex ツールを使用すると、圧縮したテクスチャ (DDS) ファイルの作成と変換を行うことができる。独自の DDS ファイルを作成することもできる。

この動作の利点は、アプリケーションで、特定のフォーマットで特定の幅と高さを持つサーフェスに必要なストレージ容量を計算しなくても圧縮したサーフェスのコンテンツをファイルにコピーできることである。

圧縮したテクスチャの 5 つのタイプを以下の表に示す。データの保存方法の詳細については、「圧縮したテクスチャ フォーマット」を参照すること。次の情報は、独自の圧縮ルーチンを記述する場合に必要である。

FOURCC | 説明 | アルファ値事前掛け算済み
DXT1 | 不透明/1 ビット アルファ | N/A
DXT2 | 明示的なアルファ | Yes
DXT3 | 明示的なアルファ | No
DXT4 | 補間したアルファ | Yes
DXT5 | 補間したアルファ | No

注 値事前掛け算済みではないフォーマットから値事前掛け算済みのフォーマットにデータを転送する場合、Direct3D はアルファ値を基に色をスケーリングする。値事前掛け算済みのファーマットから値事前掛け算済みではないフォーマットへのデータ転送はサポートされない。値事前掛け算済みのアルファ転送元から値事前掛け算済みではないアルファ転送先へのデータ転送を試すと、メソッドは D3DERR_INVALIDCALL を返す。値事前掛け算済みのアルファ転送元からアルファがない転送先にデータを転送すると、アルファでスケーリングされる転送元色成分はそのままコピーされる。


圧縮したテクスチャの復元

テクスチャ サーフェスの圧縮と同様、圧縮したテクスチャの復元は Microsoft®Direct3D® コピー サービスによって行うことができる。

ドライバがビデオ メモリ サーフェスの作成をサポートする場合は、圧縮したビデオ メモリ サーフェスから圧縮していないビデオやシステム メモリ サーフェスへのコピーにおける圧縮の復元も行う。

圧縮したシステム メモリ サーフェスから圧縮していないビデオ メモリ サーフェスへのコピーは多くの場合サポートされず、ドライバが圧縮したテクスチャをサポートする場合でもサポートされない。これは、圧縮したシステム メモリ サーフェスの圧縮の復元と、ビデオ メモリ サーフェスへのコンテンツの移動が不可能であることを示しているわけではない。単に、追加のステップを必要とするだけである。

ビデオ メモリへのシステム メモリ サーフェスの圧縮を復元するには

  1. 必要なディメンジョンとピクセル フォーマットのシステム メモリに、圧縮していないオフスクリーン プレーン サーフェスを作成する。
  2. 圧縮したシステム メモリ サーフェスから圧縮していないシステム メモリ サーフェスにコピーする
  3. 圧縮していないサーフェスから圧縮していないビデオ メモリ サーフェスにコピーする。


ボリューム テクスチャ リソース

以下のトピックでは、ボリューム テクスチャについて説明する。

  • ボリューム テクスチャとは
  • ボリューム テクスチャの使い方


ボリューム テクスチャとは

ボリューム テクスチャとは、三角形や線などの 2D プリミティブの描画に使用できるピクセル (テクセル) の 3D の集まりのことである。立体でテクスチャ処理されるプリミティブの各頂点には、3 要素のテクスチャ座標が必要である。プリミティブを描画する場合、各プリミティブに含まれるピクセルには、2D テクスチャの場合と同じような規則に従って、立体内のピクセルのカラー値が設定される。立体でペイントできる 3D プリミティブがないため、立体は直接レンダリングされない。

ボリューム テクスチャは、まだらなフォグ、爆発などの特殊効果に使用できる。

立体はスライスにまとめられ、幅 × 高さの 2D サーフェスがスタックされて、幅 × 高さ × 奥行きの立体を構成すると考えることができる。各スライスは、単一行である。立体は後続レベルを持つことができる。各レベルの大きさは、直前レベルの半分の大きさに切り捨てられる。次の図は、複数レベルを持つボリューム テクスチャを示している。


ボリューム テクスチャの使い方

次のコードは、ボリューム テクスチャを使用するために必要な手順を示している。

まず、各頂点に対して 3 つのテクスチャ座標を持つカスタム頂点タイプを指定する。次のコードに例を示す。

Private Type VOLUMEVERTEX
    Dim x As Single
    Dim y As Single
    Dim z As Single
    Dim color As Long
    Dim tu As Single
    Dim tv As Single
    Dim tw As Single
};

Const D3DFVF_VOLUMEVERTEX = (D3DFVF_XYZ Or D3DFVF_DIFFUSE Or _
                             D3DFVF_TEX1 Or D3DFVF_TEXCOORDSIZE3_0)

次に、頂点にデータを設定する。

Dim Vertices(3) As VOLUMEVERTEX

With Vertices(0):
    .x = 1.0: .y = 1.0: .z = 0.0: .color = &HFFFFFFFF .tu = 1.0: .tv = 1.0: .tw = 0.0
End With

With Vertices(1):
    .x = -1.0: .y = 1.0: .z = 0.0: .color = &HFFFFFFFF .tu = 0.0: .tv = 1.0: .tw = 0.0
End With

With Vertices(2):
    .x = 1.0: .y = -1.0: .z = 0.0: .color = &HFFFFFFFF .tu = 1.0: .tv = 0.0: .tw = 0.0
End With

With Vertices(3):
    .x = -1.0: .y = -1.0: .z = 0.0: .color = &HFFFFFFFF .tu = 0.0: .tv = 0.0: .tw = 0.0
End With

次に、頂点バッファを作成し、頂点のデータを設定する。

次の手順は、Direct3DDevice8.CreateVolumeTexture メソッドを使用して頂点シェーダを作成することである。次のコードにその例を示す。

Dim volTexture As Direct3DVolumeTexture8

Set volTexture = m_D3DDevice.CreateVolumeTexture(8, 4, 4, 1, 0, _
                                                 D3DFMT_R8G8B8, _
                                                 D3DPOOL_MANAGED)

プリミティブをレンダリングする前に、カレント テクスチャを前の手順で作成したボリューム テクスチャに設定する。次のコードは、三角形のストリップのレンダリング プロセス全体を示している。

d3dDevice.BeginScene

' ボリューム テクスチャで四角形を描画する。
Call d3dDevice.SetTexture(0, volTexture)
Call d3dDevice.SetVertexShader(D3DFVF_VOLUMEVERTEX)
Call d3dDevice.SetStreamSource(0, VB, len(Vertices(0))
Call d3dDevice.DrawPrimitive(D3DPT_TRIANGLESTRIP, 0, 2)

' シーンを終了する。
d3dDevice->EndScene


自動テクスチャ管理

テクスチャ管理とは、ある時点においてどのテクスチャがレンダリングに必要であるかを判断し、それらのテクスチャをビデオ メモリに確実にロードする処理である。ほかのアルゴリズムと同様、テクスチャ管理スキームもその複雑さはさまざまであるが、どのようなアプローチでテクスチャ管理を行う場合であっても、以下に示すタスクが重要である。

  • 使用可能なテクスチャ メモリの量の追跡
  • レンダリングに必要なテクスチャと不要なテクスチャの計算
  • 既存のテクスチャ リソースのうち、ほかのテクスチャ画像に再ロードできるテクスチャ リソースの判断、また破棄する必要があるサーフェス、および新しいテクスチャ リソースで置き換える必要があるサーフェスの判断

Microsoft® Direct3D® では、システムによるテクスチャ管理が実装されており、テクスチャはパフォーマンス最適化のために確実にロードされる。Direct3D が管理するテクスチャ リソースを管理下のテクスチャと呼ぶ。

テクスチャ マネージャは、テクスチャの最終使用時を示すタイムスタンプを利用してテクスチャを追跡する。次に、LRU (least-recently-used) アルゴリズムを用いて、削除する必要があるテクスチャを判断する。メモリから削除するテクスチャが 2 つある場合、テクスチャの優先度に基づいてテクスチャが削除される。2 つのテクスチャの優先度が同じ場合は、最終使用時が新しい方のテクスチャが削除される。ただし、2 つのテクスチャでタイムスタンプが同じ場合は、優先度の低いテクスチャが先に削除される。

テクスチャを作成するときに、そのテクスチャの自動テクスチャ管理を要求する。Microsoft® Visual Basic® アプリケーションで管理下のテクスチャを取得するには、Direct3DDevice8.CreateTexture を呼び出し、Pool パラメータに D3DPOOL_MANAGED を指定して、テクスチャ リソースを作成する。ただし、テクスチャの作成場所を指定することはできない。管理下のテクスチャを作成するときには、D3DPOOL_DEFAULT または D3DPOOL_SYSTEMMEM フラグは使用できない。管理下のテクスチャを作成した後、Direct3DDevice8.SetTexture メソッドを呼び出して、その管理下のテクスチャをレンダリング デバイスのテクスチャ カスケードのステージに設定できる。

テクスチャ サーフェスに対して Direct3DResource8.SetPriority メソッドを呼び出して、管理下のテクスチャに優先度を割り当てることができる。

Direct3D では、必要に応じてテクスチャをビデオ メモリに自動的にダウンロードできるシステムは、非ローカル ビデオ メモリやその他の要素が使用可能であるかどうかによって、管理下のテクスチャをローカルまたは非ローカル ビデオ メモリにキャッシュする。管理下のテクスチャがキャッシュされる場所は、アプリケーションに通知されない。自動テクスチャ管理を利用する際に、この情報は必要ない。アプリケーションで使用するテクスチャがビデオ メモリに収まらないほどある場合、Direct3D はビデオ メモリから古いテクスチャを削除して、新しいテクスチャ用の領域を確保する。削除したテクスチャを再度使用する場合、システムはオリジナル システムメモリ テクスチャ サーフェスを使用して、テクスチャをビデオメモリ キャッシュに再ロードする。テクスチャの再ロードが必要であるが、これを行うとアプリケーションのパフォーマンスが低下する。

テクスチャ リソースを更新またはロックすることで、テクスチャのオリジナル システム メモリ コピーを動的に変更できる。ダーティー サーフェスが検出された場合 (更新の完了後、またはサーフェスのロック解除時)、テクスチャ マネージャはテクスチャのビデオ メモリ コピーを自動的に更新する。このときのパフォーマンスは、削除されたテクスチャを再ロードする場合と同様である。

ゲームで新しいレベルに移る際、アプリケーションでビデオ メモリからすべての管理下のテクスチャをフラッシュしなければならないときがある。すべての管理下のテクスチャを削除するよう明示的に要求するには、Direct3DDevice8.ResourceManagerDiscardBytes メソッドを呼び出して、Bytes パラメータに 0 の値を指定する。このメソッドを呼び出すと、キャッシュされているローカルまたは非ローカル ビデオメモリ テクスチャが Direct3D によって破棄されるが、オリジナル システムメモリ コピーはそのまま残る。

リソース管理の詳細については、「リソースの管理」を参照すること。


テクスチャ処理におけるハードウェアによる制約

現在のハードウェアが、Microsoft® Direct3D® インターフェイスによって可能になる機能をすべて実装しているとは限らない。アプリケーションでユーザーのハードウェアをテストし、それに応じてレンダリング方法を調整する必要がある。

3D アクセラレータ カードの多くは、ブレンディング ユニットへの引数としてディフューズ補間値をサポートしていない。ただし、テクスチャ ブレンディングを実行する際は、アプリケーションで補間色データを導入できる。

3D ハードウェアによっては、ブレンディング ステージを最初のテクスチャに関連付けることができない場合もある。このようなアダプタの場合、アプリケーションではカレント テクスチャ セットの 2 番目および 3 番目のステージでブレンディングを実行する必要がある。

現時点では多くのハードウェアで制約があるため、Direct3DDevice8 が提供するマルチ テクスチャ ブレンディング インターフェイスによるトライリニア ミップマップ補間を実行できるディスプレイ アダプタは少数である。特に、D3DTSS_MIPFILTER テクスチャ ステージ ステートを D3DTEXF_LINEAR に設定できるものはほとんどない。アプリケーションでマルチパス テクスチャ ブレンディングを使用して同じエフェクトを得るか、広くサポートされている D3DTEXF_POINT ミップマップ フィルタ モードを使用するとよい。


深度バッファ

ここでは、深度バッファを使用して隠線と隠面を消す方法について説明する。説明するトピックは、次のとおりである。

  • 深度バッファとは
  • 深度バッファの使い方


深度バッファとは

z バッファまたは w バッファと呼ばれる深度バッファとは、Microsoft® Direct3D® で使用する奥行き情報を格納するデバイスのプロパティである。Direct3D が 3D シーンをターゲット サーフェスにレンダリングするとき、アタッチされた深度バッファ サーフェスのメモリを作業空間として使用して、ラスタ化したポリゴンのピクセルが互いにどのように覆い合うのかを判定できる。Direct3D は、オフスクリーン Direct3D サーフェスを、最終的なカラー値を書き込むターゲットとして使用する。レンダリング ターゲット サーフェスに関連する深度バッファ サーフェスは、シーンでの可視的ピクセルそれぞれの深さを Direct3D に知らせる深度情報の格納に使用する。

深度バッファリングを有効にして 3D シーンをラスタ化するとき、レンダリング サーフェス上の各ポイントが調べられる。深度バッファの値は、ポイントの z 座標または同次 w 座標 (射影空間のポイントの (x,y,z,w) 位置座標の) でありうる。z 値を使用する深度バッファは Z バッファと呼ばれ、w 値を使用する深度バッファは W バッファと呼ばれる。どの種類の深度バッファにも利点と欠点があるが、これについては後で説明する。

テストの最初に、深度バッファの深度値をシーンで可能な最大値に設定する。レンダリング サーフェス上のカラー値は、背景のカラー値またはそのポイントの背景テクスチャのカラー値に設定する。シーンの各ポリゴンを調べて、レンダリング サーフェス上のカレント座標 (x,y) に当たるかどうかを確かめる。交差する場合、現在のポイントでの深度値 (Z バッファの Z 座標または W バッファの W 座標) をテストして、深度バッファに既に格納されている深度値よりも小さいかどうかを確認する。ポリゴンの深度値の方が小さければ、その値が深度バッファに格納され、そのポリゴンからのカラー値がレンダリング サーフェス上の現在のポイントに書き込まれる。そのポイントでのポリゴンの深度値の方が大きければ、リストの次のポリゴンが調べられる。次の図に、この処理を示す。

注 ほとんどのアプリケーションではこの機能を使用しないが、深度バッファに入る値とレンダリング ターゲット サーフェスを判定するために Direct3D が使用するこの比較を変更できる。これを行うには、D3DRS_ZFUNC レンダリング ステートの値を変更すること。

現在では、市販のほとんどすべての 3D アクセラレータが、z バッファリングをサポートしており、Z バッファが最も一般的な深度バッファの種類になっている。しかし、Z バッファにも欠点がある。使用する数学的処理が原因で、Z バッファに生成される z 値は、Z バッファの範囲 (通常 0.0 から 1.0) 全体に均等に分散されない傾向がある。特に、遠くのクリップ面と近くのクリップ面の間の比率は、z 値の不均一な分散に強い影響を与える。近くの平面の距離に対する遠くの平面の距離の比率を 100% とした場合、深度バッファ範囲の 90% がシーンの深度範囲の最初の 10% に費やされる。娯楽や風景のシミュレーション用の典型的なアプリケーションでは、比率 (遠くの平面 / 近くの平面) がどこでも 1000 から 10000 の間である必要がある。比率が 1000 の場合、深度バッファ範囲の98% が深度範囲の最初の 2% に費やされ、比率が高くなるにつれて分散状態が悪くなる。これによって、遠くのオブジェクトでサーフェス ディテールが隠れてしまうことがある。これは、特に 16 ビット深度 (最も一般的なビット深度) バッファを使用する場合に顕著である。

一方、W 深度バッファでは、Z バッファの場合よりも、近くのクリップ面と遠くのクリップ面の間の分散がより均等である。したがって、遠くのクリップ面と近くのクリップ面の距離の比率が問題にならないという利点がある。これによって、アプリケーションは大きな最大範囲をサポートできる。ただし、視点に近い正確な深度バッファリングといっても相対的なものである。W 深度バッファは完璧ではなく、近くのオブジェクトのサーフェス ディテールが隠れることがある。もう 1 つの欠点は、ハードウェア サポートに関係することである。つまり、w バッファリングはハードウェアで z バッファリングほど広くはサポートされていない。

z バッファリングには、レンダリングのときにオーバーヘッドがある。Z バッファを使用するときに、レンダリングを最適化するために使用できるさまざまな技術がある。詳細については、「Z バッファのパフォーマンス」を参照すること。

注 深度値の実際の解釈は、3D レンダラによって異なる。


深度バッファの使い方

ここでは、一般的な深度バッファの使用方法について説明する。

  • 深度バッファのサポート状況の問い合わせ
  • 深度バッファの作成
  • 深度バッファリングを有効にする
  • 深度バッファの取得
  • 深度バッファのクリア
  • 深度バッファへの書き込みアクセスの変更
  • 深度バッファ比較関数の変更
  • Z バイアスの使い方

参照

深度バッファとは


深度バッファのサポート状況の問い合わせ

ほかの機能でも同様だが、アプリケーションで使用するドライバがあらゆる種類の深度バッファリングをサポートしているとは限らない。常にドライバの機能を調べる必要がある。z ベースの深度バッファリングはほとんどのデバイスでサポートされているが、w ベースの深度バッファリングは一部のデバイスでしかサポートされていない。サポートされていないスキームを有効にしても、ドライバは失敗しない。ドライバは別の深度バッファリングに頼ったり、場合によってはすべての深度バッファリングを無効にし、その結果、レンダリング後のシーンに深度ソートによる不自然な効果が現れることがある。

Direct3D デバイスを作成する前にアプリケーションで使用するディスプレイ デバイスについて Microsoft® Direct3D® に問い合わせることで、深度バッファのサポートを調べることができる。Direct3D オブジェクトから深度バッファリングをサポートしているとの報告があれば、この Direct3D オブジェクトから作成するハードウェア デバイスは z バッファリングをサポートする。

Visual Basic アプリケーションで一般的な深度バッファリングのサポート状況を照会するには

深度バッファリングのサポート状況を問い合わせるには、Direct3D8.CheckDeviceFormat メソッドを使用する。次のコードは、その例を示している。

' 次の例では、g_D3D、AdapterOrdinal、DeviceType、
' および Format は、正しく初期化された値であると仮定している。
g_D3D.CheckDeviceFormat AdapterOrdinal, DeviceType, Format, _
                        D3DUSAGE_DEPTHSTENCIL, D3DRTYPE_SURFACE, _
                        D3DFMT_D16

CheckDeviceFormat では、該当するデバイスの能力に基づいて、作成するデバイスを選択できる。この場合、16 ビットの深度バッファをサポートしないデバイスは拒否される。

また、Direct3D8.CheckDepthStencilMatch を使用して、サポートされている深度ステンシル フォーマットがディスプレイ モードのレンダリング ターゲットのフォーマットと互換性があるかどうか、特に、深度フォーマットがレンダリング ターゲットのフォーマットと等しいかどうかを調べることができる。

ドライバで深度バッファがサポートされていることがわかったら、次は w バッファのサポート状況を調べることができる。深度バッファはすべてのソフトウェア ラスタライザでサポートされているが、w バッファはリファレンス ラスタライザでしかサポートされていない。これでは、実際のアプリケーションでの使用に適さない。アプリケーションで使用するデバイスがどのような種類でも、w ベース深度バッファリングを有効にする前に、w バッファのサポート状況を調べる必要がある。

Visual Basic アプリケーションで w バッファのサポート状況を調べるには

  1. デバイスを作成した後、Direct3DDevice8.GetDeviceCaps メソッドを呼び出して、初期化された D3DCAPS8 型を渡す。
  2. この呼び出しの後、プリミティブのレンダリングに関するドライバのサポートの情報が LineCaps メンバに入る。
  3. この型の RasterCaps メンバに D3DPRASTERCAPS_WBUFFER フラグが含まれている場合、ドライバは当該のプリミティブ タイプに対する W 深度バッファリングをサポートする。

深度バッファリングの一般情報については、「深度バッファとは」を参照すること。


深度バッファの作成

深度バッファはデバイスのプロパティである。Microsoft® Direct3D® によって管理される深度バッファを作成するには、D3DPRESENT_PARAMETERS 構造体の適切なメンバを設定する。次のコードは、その例を示している。

Dim d3dpp As D3DPRESENT_PARAMETERS

d3dpp.Windowed = 1
d3dpp.SwapEffect = D3DSWAPEFFECT_COPY_VSYNC
d3dpp.EnableAutoDepthStencil = 1
d3dpp.AutoDepthStencilFormat = D3DFMT_D16

EnableAutoDepthStencil メンバをゼロ以外の値 (TRUE) に設定して、アプリケーションの深度バッファを管理するよう Direct3D に指示する。AutoDepthStencilFormat は有効な深度バッファ フォーマットに設定すること。D3DFMT_D16 フラグは、16 ビットの深度バッファが使用できる場合は、それを指定する。

次の Direct3D8.CreateDevice メソッドの呼び出しは、深度バッファを作成するデバイスを作成する。

Set d3dDevice = g_D3D.CreateDevice(D3DADAPTER_DEFAULT, D3DDEVTYPE_HAL, hWnd, _
                                     D3DCREATE_SOFTWARE_VERTEXPROCESSING, d3dpp)
If d3dDevice Is Nothing Then Exit Function

深度バッファは、デバイスのレンダリング ターゲットとして自動的に設定される。デバイスがリセットされると、深度バッファは自動的に破棄され、新しいサイズで再作成される。

新しい深度バッファ サーフェスを作成するには、Direct3DDevice8.CreateDepthStencilSurface メソッドを使用する。

デバイスの新しい深度バッファ サーフェスを設定するには、Direct3DDevice8.SetRenderTarget メソッドを使用する。

アプリケーションで深度バッファを使用するには、深度バッファを有効にする必要がある。詳細については、「深度バッファリングを有効にする」を参照すること。


深度バッファリングを有効にする

「深度バッファの作成」で説明したように深度バッファを作成した後、Direct3DDevice8.SetRenderState メソッドを呼び出して深度バッファリングを有効にする。D3DRS_ZENABLE レンダリング ステートを設定して深度バッファを有効にする。z バッファリングを有効にするには CONST_D3DZBUFFERTYPE 列挙の D3DZB_TRUE メンバを、w バッファリングを有効にするには D3DZB_USEW を、深度バッファリングを無効にするには D3DZB_FALSE をそれぞれ設定する。

注 w バッファリングを使用するには、アプリケーションで Microsoft® Direct3D® トランスフォーム パイプラインを使用しない場合であっても、対応する射影行列を設定しなければならない。適切な射影行列の設定については、「W バッファに有効な射影行列」を参照すること。「射影トランスフォームとは」で説明する射影行列は適切なものである。


深度バッファの取得

次のサンプル コードは、Direct3DDevice8.GetDepthStencilSurface メソッドを使用して、デバイスが所有する深度バッファ サーフェスを取得する方法を示している。

    Dim ZBuffer As Direct3DSurface8

    Set ZBuffer = d3dDevice.GetDepthStencilSurface


深度バッファのクリア

多くの Microsoft® Visual Basic® アプリケーションは、新しいフレームをレンダリングする前に深度バッファをクリアする。Direct3DDevice8.Clear を呼び出して Flags パラメータに D3DCLEAR_ZBUFFER を指定することにより、Microsoft® Direct3D® で深度バッファを明示的にクリアできる。Clear メソッドでは、Z パラメータに任意の深度値を指定できる。


深度バッファへの書き込みアクセスの変更

デフォルトでは、Microsoft® Direct3D® システムは深度バッファへの書き込みが許されている。ほとんどのアプリケーションでは深度バッファへの書き込みを有効にしたままであるが、Direct3D システムによる深度バッファへの書き込みを禁止することによって、特殊効果を生成することができる。

Microsoft Visual Basic® アプリケーションで深度バッファへの書き込みを無効にするには、State パラメータを D3DRS_ZWRITEENABLE に設定し、Value パラメータを 0 に設定して Direct3DDevice8.SetRenderState メソッドを呼び出す。


深度バッファ比較関数の変更

デフォルトでは、レンダリング サーフェスの深度テストを行うとき、Microsoft® Direct3D® システムは、各ポイントに対応する深度値 (z または w) が深度バッファの既存の値より小さい場合、レンダリングターゲット サーフェスを更新する。Microsoft® Visual Basic® アプリケーションで、システムによる深度値の比較方法を変更するには、State パラメータを D3DRS_ZFUNC に設定して Direct3DDevice8.SetRenderState メソッドを呼び出す。Value パラメータには、CONST_D3DCMPFUNC 列挙の値を設定する必要がある。


Z バイアスの使い方

3D 空間で同一平面上にあるポリゴンは、それぞれのポリゴンに Z バイアスを追加することで、あたかも同一平面上にないように表示することができる。この技術は、シーン内の影を正しく表示するために使用されることが多い。たとえば、壁上の影の深度値が壁の深度値と同じになる可能性がある。最初に壁をレンダリングし、次に影をレンダリングすると、影が見えないか、または深度による不自然な効果が見える。同一平面上のオブジェクトのレンダリング順を逆にすると、これとは逆のエフェクトが得られるが、深度による不自然な効果が残ったままであることが多い。

Microsoft® Visual Basic® アプリケーションでは、同一平面上のポリゴン セットをレンダリングする際にシステムが使用する z 値にバイアスを追加することで、同一平面上のポリゴンを正しくレンダリングできる。z バイアスをポリゴン セットに追加するには、レンダリングの直前に Direct3DDevice8.SetRenderState メソッドを呼び出す。このとき、State パラメータを D3DRS_ZBIAS に設定し、Value パラメータを 0 と 16 を含む 0 ～ 16 の値に設定する。z バイアス値が高いほど、同一平面上のほかのポリゴンと共に表示するとき、レンダリングするポリゴンが見える可能性が高くなる。


ステンシル バッファ

ここでは、ステンシル バッファの目的と使用方法について説明する。説明するトピックは、次のとおりである。

  • ステンシル バッファとは
  • ステンシル バッファの動作
  • ステンシル バッファのカスタマイズ


ステンシル バッファとは

ステンシル バッファは、レンダリング ターゲット サーフェスのピクセル単位の描画を有効または無効にする。このバッファの最も基本的なレベルでは、アプリケーションがレンダリングした画像の部分をマスクで覆うことが可能になり、その画像が表示されない。アプリケーションはディゾルブ、デカーリング、およびアウトライニングなどの特殊効果のためにステンシル バッファを使用することが多い。詳細については、「ステンシル バッファ技術」を参照すること。

ステンシル バッファ情報は、Z バッファ データに埋め込まれている。Direct3D8.CheckDeviceFormat を使用して、ハードウェアがステンシル バッファをサポートしているかどうかを調べることができる。次のコードに例を示す。

' 次の例では、g_D3D、AdapterOrdinal、DeviceType、
' および Format は、正しく初期化された値であると仮定している。

g_D3D.CheckDeviceFormat AdapterOrdinal, DeviceType, Format, _
                        D3DUSAGE_DEPTHSTENCIL, D3DRTYPE_SURFACE, _
                        D3DFMT_D24S8
If Err.Number <> D3D_OK Then
    ' エラーを処理する。
End If

CheckDeviceFormat では、該当するデバイスの能力に基づいて、作成するデバイスを選択できる。この場合、8 ビットのステンシル バッファをサポートしないデバイスは、Err.Number をエラー値に設定する。これは CheckDeviceFormat で使用できる方法の 1 つにすぎない。詳細については、「ハードウェア サポートの判定」を参照すること。

デバイスでのステンシル バッファ制限を調べるには、サポートされているステンシル バッファ処理について D3DCAPS8 型の StencilCaps メンバに問い合わせる。


ステンシル バッファの動作

Microsoft® Direct3D® は、ステンシル バッファの内容をピクセル単位に調べる。ステンシル バッファの対応する値、ステンシル参照値、およびステンシル マスク値を使用して、ターゲット サーフェスの各ピクセルに対するテストを行う。テストにパスすると、Direct3D はアクションを実行する。このテストは次の手順で実行される。

  1. ステンシル参照値とステンシル マスクのビット積を計算する。
  2. カレント ピクセルに対するステンシル バッファ値とステンシル マスクのビット積を計算する。
  3. 比較関数を使用して、手順 1 と手順 2 の結果を比較する。

これらのステップを次の例で示す。

(StencilRef And StencilMask) CompFunc (StencilBufferValue And StencilMask)

ここで、StencilBufferValue は、カレント ピクセルに対するステンシル バッファの内容である。StencilMask はステンシル マスク、StencilRef はステンシル参照値を表している。CompFunc は比較関数である。

このステンシル テストにパスすると、カレント ピクセルはターゲット サーフェスに書き込まれるが、失敗した場合は無視される。デフォルトの比較処理では、各ビット演算の結果に関係なく、ピクセルが書き込まれる (D3DCMP_ALWAYS)。この動作を変更するには、目的の比較関数を指定する CONST_D3DCMPFUNC 列挙のメンバを渡して、D3DRS_STENCILFUNC レンダリング ステートの値を変更する。


ステンシル バッファのカスタマイズ

アプリケーションでは、ステンシル バッファの処理をカスタマイズできる。アプリケーションでは、比較関数、ステンシル マスク、およびステンシル参照値を設定できる。また、ステンシル テストにパスした場合または失敗した場合に実行する Microsoft® Direct3D® の処理を制御することもできる。詳細については、「ステンシル バッファ ステート」を参照すること。


頂点バッファ

ここでは、Microsoft® Direct3D® アプリケーションにおいて頂点バッファを理解し、使用するのに必要な概念を説明する。説明するトピックは、次のとおりである。

  • 頂点バッファとは
  • 頂点バッファの記述
  • 頂点バッファのプールと使用
  • FVF 頂点バッファ
  • デバイスの種類と頂点処理の要件
  • 頂点バッファの使い方


頂点バッファとは

頂点バッファとは、Direct3DVertexBuffer8 クラスで表される、頂点データを含むメモリ バッファである。頂点バッファは、トランスフォーム済みの頂点、未トランスフォームの頂点、ライティング済みの頂点、未ライティングの頂点など、Direct3DDevice8 クラスの頂点バッファ レンダリング メソッドでレンダリング可能なあらゆる種類の頂点を含むことができる。頂点バッファ内の頂点を処理して、トランスフォーム、ライティング、クリッピング フラグの生成などの処理を実行できる トランスフォームは常に実行される。

頂点バッファは柔軟なので、トランスフォームされたジオメトリを再使用するための理想的なステージ ポイントとなる。単一の頂点バッファを作成して、頂点をトランスフォーム、ライティングを適用、およびその頂点バッファに頂点を切り取り、たとえインタリーブされたレンダリング ステートが変化した場合でも、シーンのモデルを何度も再トランスフォームせずにレンダリングできる。これは、マルチ テクスチャを使用するモデルのレンダリングの際に便利である。ジオメトリを一度トランスフォームすれば、要求されたテクスチャの変更に合わせてインタリーブして、必要に応じてその一部をレンダリングできる。頂点を処理した後で変更したレンダリング ステートは、次に頂点を処理するときに有効になる。詳細については、「頂点の処理」を参照すること。


頂点バッファの記述

頂点バッファの記述は、能力について行う。頂点バッファは、システム メモリ内にだけ存在できるのか、書き込み操作だけに使用されるのか、頂点バッファが含むことができる頂点の種類と数などを記述する。これらの特性はすべて D3DVERTEXBUFFER_DESC 型に保持される。

頂点バッファの記述によって、アプリケーションは、既存バッファが作成された方法および作成後に最適化されたかどうかを知ることができる。システムが作成済み頂点バッファの能力を書き込めるように、空白の記述構造体を用意する。このタスクの詳細については、「頂点バッファの記述の取得」を参照すること。

format メンバは、頂点バッファ データのサーフェス フォーマットの記述に使用する。type は、頂点バッファのリソース タイプを識別する。Usage 構造体のメンバは、一般的な能力フラグを格納する。D3DUSAGE_SOFTWAREPROCESSING フラグは、その頂点バッファがソフトウェア頂点処理に使用されることを示す。Usage に D3DUSAGE_WRITEONLY フラグがある場合は、頂点バッファ メモリは書き込み処理のみに使用される。これによりドライバは解放され、高速処理と高速レンダリングを可能にする最適なメモリ位置に頂点データが配置される。D3DUSAGE_WRITEONLY フラグが使用されていない場合、ドライバは、読み出し処理に効率の悪い位置にデータを配置しないようにする。これにより、処理速度やレンダリング速度が多少犠牲になる。このフラグが使用されていない場合、アプリケーションは、頂点バッファ内のデータで読み書きの処理を実行すると見なされる。

Pool は、頂点バッファに割り当てられるメモリ クラスを指定する。D3DPOOL_SYSTEMMEM フラグは、システムがシステム メモリ内に頂点バッファを作成したことを示す。

size メンバは、単に頂点バッファ データのサイズをバイト数で格納する。FVF メンバは、バッファが格納する頂点のタイプを識別する柔軟な頂点フォーマット フラグの組み合わせを格納する。


頂点バッファのプールと使用

頂点バッファは、Direct3DDevice8.CreateVertexBuffer メソッドで作成し、このメソッドはプール (メモリ クラス) と使用パラメータを取る。CreateVertexBuffer は、固定機能頂点処理またはプロセス頂点の出力として使用するため、柔軟な頂点フォーマット (FVF) コードを指定して作成することもできる。詳細については、「FVF 頂点バッファ」および「転送先頂点バッファの FVF 使用設定」を参照すること。

D3DUSAGE_SOFTWAREPROCESSING フラグは、そのデバイスに対してミックス モードまたはソフトウェア頂点処理 (D3DCREATE_MIXED_VERTEXPROCESSING / D3DCREATE_SOFTWARE_VERTEXPROCESSING) が有効になっているときに設定できる。D3DUSAGE_SOFTWAREPROCESSING はミックス モードでのソフトウェア頂点処理に使用するバッファに設定し、ミックス モードでのハードウェア頂点処理 (D3DCREATE_HARDWARE_VERTEXPROCESSING) 時に最高のパフォーマンスを得たいときは設定してはならない。ただし、単一のバッファがハードウェアおよびソフトウェア頂点処理の両方で使用される場合、D3DUSAGE_SOFTWAREPROCESSING を設定する以外のオプションはない。D3DUSAGE_SOFTWAREPROCESSING は、ソフトウェア デバイスだけでなくミックスにも設定することができる。

頂点処理がハードウェアで実行される場合でも、D3DPOOL_SYSTEMMEM を指定すれば、頂点バッファとインデックス バッファをシステム メモリ内に強制的に配置することができる。これは、ドライバによってこれらのバッファが AGP メモリに入れられたときに、ページ ロックされるメモリが多くなりすぎないようにする方法である。


FVF 頂点バッファ

有効な FVF コードで Direct3DDevice8.CreateVertexBuffer の FVF パラメータをゼロ以外の値に設定すると、バッファの内容は FVF コードによって特性付けられる。FVF コードで作成された頂点バッファを、FVF 頂点バッファという。Direct3DDevice8 のメソッドや使用によっては、FVF 頂点バッファを必要とする場合と非 FVF 頂点バッファを必要とする場合がある。FVF 頂点バッファは、Direct3DDevice8.ProcessVertices の転送先頂点バッファ引数として必要である。

FVF 頂点バッファは、任意のストリーム番号の転送元データ ストリームにバインドできる。ただし、FVF 頂点バッファは、プログラムされた頂点シェーダへの入力として使用することはできない。

FVF 頂点バッファに D3DFVF_XYZRHW コンポーネントがある場合は、そのバッファ内の頂点が処理されていることを示す。ProcessVertices 転送先頂点バッファに使用される頂点バッファは、処理後の頂点バッファでなければならない。固定機能シェーダの入力に使用される頂点バッファは、処理前でも処理後でもかまわない。頂点バッファが処理後の場合には、シェーダはバイパスされ、プリミティブ クリッピングおよびセットアップ モジュールに直接データが渡される。

FVF 頂点バッファは、頂点シェーダと共に使用することができる。また、頂点ストリームは、非 FVF 頂点バッファが表すことのできる頂点フォーマットと同じ頂点フォーマットを表すことができる。別の頂点バッファからのデータを入力するために使用する必要はない。新しい頂点ストリームが持つ柔軟性により、データを別に維持する必要のあるアプリケーションでは、より高速な処理が行えるようになるが、これは必須ではない。アプリケーションがあらかじめインターリーブされたデータを保持できる場合は、パフォーマンスが向上する。アプリケーションが各レンダリング呼び出しの前にデータをインターリーブするだけの場合は、アプリケーション プログラミング インターフェイス (API) またはハードウェアに複数のストリームでこの処理を行わせなければならない。

頂点のパフォーマンスで最も重要なことは、32 バイトの頂点を使用し、良いキャッシュ順を保持することである。


デバイスの種類と頂点処理の要件

トランスフォームやライティングなどの頂点処理のパフォーマンスは、頂点バッファのメモリ内での位置座標と、使用されるレンダリング デバイスの種類に大きく依存する。頂点バッファを作成すると、アプリケーションはその頂点バッファへのメモリ割り当てを制御できる。D3DPOOL_SYSTEMMEM メモリ フラグが設定されているときは、システム メモリ内に頂点バッファが作成される。D3DPOOL_DEFAULT メモリ フラグを使用すると、頂点バッファ用のメモリの最良の割り当て場所をデバイス ドライバが決定し、このようにして決定されたメモリのことを多くの場合ドライバ最適化メモリと呼ぶ。ドライバ最適化メモリとしては、ローカル ビデオ メモリ、非ローカル ビデオ メモリ、またはシステム メモリが指定される。

D3DUSAGE_SOFTWAREPROCESSING 動作フラグを設定して Direct3DDevice8.CreateVertexBuffer メソッドを呼び出すと、頂点バッファはソフトウェア頂点処理に使用される。このフラグは、混合頂点処理モードにおけるソフトウェア頂点処理で必要である。このフラグは、ソフトウェア頂点処理モードでは使用できるが、ハードウェア頂点処理モードでは使用できない。ソフトウェア頂点処理に使用される頂点バッファを次に示す。

  • Direct3DDevice8.ProcessVertices のすべての入力ストリーム。
  • ソフトウェア頂点処理における、Direct3DDevice8.DrawPrimitive および Direct3DDevice8.DrawIndexedPrimitive のすべての入力ストリーム。詳細については、「D3DRS_SOFTWAREVERTEXPROCESSING」を参照すること。

頂点バッファがシステム メモリにあるか、ドライバ最適化メモリにあるかを調べる必要があるのは、テクスチャの場合と同じ理由からである。ハードウェアにおける頂点処理 (トランスフォームやライティングなど) に最適なのは、ドライバ最適化メモリに割り当てられた頂点バッファで、ソフトウェアでの頂点処理に最適なのは、システム メモリに割り当てられた頂点バッファである。テクスチャの場合、ハードウェア ラスタ化には、ドライバ最適化メモリに割り当てられたテクスチャが最適で、ソフトウェア ラスタ化には、システム メモリに割り当てられたテクスチャが最適である。

注 Microsoft® Direct3D® for DirectX® 8.0 は、ProcessVertices メソッドでプリミティブをレンダリングしないスタンドアロン頂点処理をサポートする。このスタンドアロン頂点処理は、常にホスト プロセッサ上のソフトウェアで実行される。このため、Direct3DDevice8.SetStreamSource の転送元として設定される頂点バッファは、D3DUSAGE_SOFTWAREPROCESSING フラグで作成する必要がある。ProcessVertices の機能は、Direct3DDevice8.DrawPrimitive メソッドおよび Direct3DDevice8.DrawIndexedPrimitive メソッドがソフトウェア頂点処理において提供する機能と同じである。詳細については、「頂点の処理」を参照すること。

アプリケーションが独自の頂点処理を実行する、また、トランスフォーム済みで、ライティングが適用され、クリッピングされた頂点を頂点バッファ レンダリング メソッドに渡す場合、アプリケーションはドライバ最適化メモリに割り当てられた頂点バッファに頂点を直接書き込むことができる。この方法により、以降の冗長なコピー処理を防止する。ただし、ドライバ最適化メモリからホストによって実行される読み取り処理は、非常に処理速度が遅いことがあるため、アプリケーションが頂点バッファからデータを読み返す場合には、この方法はうまく機能しない。したがって、アプリケーションで処理中に読み取り、またはバッファへのデータ書き込みを不規則に実行する必要がある場合は、システム メモリに頂点バッファを割り当てるとよい。

Direct3D 頂点処理機能を使用する場合 (未トランスフォームの頂点を頂点バッファ レンダリング メソッドに渡して)、デバイスの種類とデバイス作成フラグに応じて、ハードウェアまたはソフトウェアのいずれかで処理が実行される。最終的にあらゆる場合において最善のパフォーマンスを得られるように、頂点バッファはプール D3DPOOL_DEFAULT に割り当てることを推奨する。デバイスがハードウェア頂点処理を使用する場合は、フラグ D3DUSAGE_DYNAMIC および D3DUSAGE_WRITEONLY に基づいて実行できる追加の最適化機能がいくつかある。これらのフラグの使用方法の詳細については、「Direct3DDevice8.CreateVertexBuffer」を参照すること。


頂点バッファの使い方

ここでは、頂点バッファ処理でアプリケーションが実行する一般的なタスクについて説明する。説明するトピックは、次のとおりである。

  • 頂点バッファの作成
  • 頂点バッファの内容へのアクセス
  • 頂点の処理
  • 頂点バッファからのレンダリング
  • 頂点バッファの記述の取得


頂点バッファの作成

5 つのパラメータを受け取る Direct3DDevice8.CreateVertexBuffer メソッドを呼び出して、頂点バッファ オブジェクトを作成する。第 1 パラメータは、頂点バッファの長さをバイト数で指定する。Microsoft Visual Basic® の Len 関数を使用して、頂点フォーマットのサイズをバイト数で指定する。次に、カスタム頂点フォーマットの例を示す。

Private Type CUSTOMVERTEX
    x As Single         ' スクリーン空間の x 座標。
    y As Single         ' スクリーン空間の y 座標。
    z  As Single        ' 正規化された z 座標。
    rhw As Single       ' 正規化された、z 座標の rhw
    color As Long       ' 頂点カラー。
    tu As Single        ' テクスチャ座標。
    tv As Single        ' テクスチャ座標。
End Type

' カスタム頂点構造体を記述するカスタム FVF。
Const D3DFVF_CUSTOMVERTEX = (D3DFVF_XYZRHW Or D3DFVF_DIFFUSE Or D3DFVF_TEX1)

4 つの CUSTOMVERTEX 構造体を保持する頂点バッファを作成するには、Length パラメータに [4*sizeof(CUSTOMVERTEX)] を指定する。

第 2 パラメータは、使用コントロール セットである。特に、この値は、頂点バッファが表示領域外の頂点のクリッピング情報を (クリップ フラグ形式で) 保持することができるかどうかを指定する。クリップ フラグを格納できない頂点バッファを作成するには、Usage パラメータに D3DUSAGE_DONOTCLIP フラグを含める。D3DUSAGE_DONOTCLIP フラグは、頂点バッファがトランスフォーム済みの頂点を保持するように指示した場合、つまり D3DFVF_XYZRHW フラグが FVF メンバに含まれる場合のみ適用される。未トランスフォームの頂点 (D3DFVF_XYZ フラグ) をバッファに含めるよう指示した場合、CreateVertexBuffer メソッドは D3DUSAGE_DONOTCLIP フラグを無視する。クリッピング フラグは追加メモリを占有するため、クリッピング可能な頂点バッファは、クリッピング フラグを含めない頂点バッファよりも若干大きくなる。リソースは頂点バッファが作成されるときに割り当てられるため、クリッピング可能な頂点バッファは先に要求しておかなければならない。

第 3 パラメータ FVF は、柔軟な頂点フォーマット フラグの組み合わせによって、頂点バッファの頂点フォーマットを記述する。このパラメータに 0 を指定した場合、頂点バッファは非 FVF 頂点バッファとなる。詳細については、「FVF 頂点バッファ」を参照すること。第 4 パラメータは、頂点バッファを格納するメモリ クラスを指定する。

CreateVertexBuffer が受け取る最後のパラメータは、呼び出しが成功したときに頂点バッファ オブジェクトの新しい Direct3DVertexBuffer8 インターフェイスへのポインタが格納される変数のアドレスである。

注 クリップ フラグをサポートしないで作成された頂点バッファにクリップ フラグを生成することはできない。

次のコードは、Visual Basic で頂点バッファを作成する方法を示している。

'
' この例では、変数 m_d3dDevice は
' 有効な Direct3DDevice8 オブジェクトである。
'

' カスタムの頂点タイプ。
Private Type CUSTOMVERTEX
    x As Single
    y As Single
    z As Single
    rhw As Single
    color As Long
    tu As Single
    tv As Single
End Type

Const D3DFVF_CUSTOMVERTEX = (D3DFVF_XYZRHW | D3DFVF_DIFFUSE | D3DFVF_TEX1)

' クリッピング可能な頂点バッファを作成する。3 つの CUSTOMVERTEX 構造体を保持するのに十分なメモリを
' デフォルトのメモリ プールに割り当てる。
VB = m_d3dDevice.CreateVertexBuffer( 3*len(CUSTOMVERTEX), _
                                     0 ' 使用 , D3DFVF_CUSTOMVERTEX, _
                                     D3DPOOL_DEFAULT)


頂点バッファの内容へのアクセス

頂点バッファを使用すると、Microsoft® Visual Basic® アプリケーションでは、頂点バッファ内の頂点データを簡単に更新できる。頂点データのロック、データの設定、ロックの解除には、D3DVertexBuffer8SetData ヘルパー関数を使用する。D3DVertexBuffer8SetData は、5 つのパラメータを受け取る。第 1 パラメータ Vbuffer は、頂点データを格納する Direct3DVertexBuffer8 オブジェクトである。第 2 パラメータ OffsetToLock は、頂点データへのオフセットである。第 3 パラメータは頂点データのサイズをバイト数で示す。

第 4 パラメータ Flags は、メモリのロック方法をシステムに知らせる。このパラメータを使って、バッファ内のデータにアプリケーションがどのようにアクセスするかを示すことができる。アプリケーションが頂点データにアクセスする方法に応じて、Flags パラメータに定数を指定する。これにより、ドライバはメモリをロックして、要求されているアクセス タイプでの最高のパフォーマンスを提供する。アプリケーションが頂点バッファ メモリから読み出しのみを行う場合は、D3DLOCK_READONLY フラグを使用する。このフラグを含めると、Microsoft® Direct3D® が内部手順を最適化するので効率が上がる。ただし、メモリへのアクセスは読み出し専用になる。

D3DVertexBuffer8SetData ヘルパー関数が受け取る最後のパラメータ Data は、頂点バッファにロードされるデータ配列の最初の要素である。このパラメータは Any 型である。このパラメータを正しく使用するためには、Data に配列の最初の要素を指定する必要がある。次のコードに例を示す。

Dim Vertices(3) As CUSTOMVERTEX
Dim VertexSizeInBytes As Long

' 頂点データの長さを指定する。
VertexSizeInBytes = Len(Vertices(0))

' 頂点にデータを設定する。
       .
       .
       .

' このサンプル コードで、g_VB は Direct3DVertexBuffer8 オブジェクトへの
' 有効な参照を格納する変数であると仮定している。

'   VBuffer=g_VB                        データを設定する頂点バッファ。
'   Offset=0                            バッファの最初から設定を開始する。
'   Size=VertSizeInBytes*3              3 つの CUSTOMVERTEX 型をバッファにコピーする。
'   Flags=0                             デフォルト フラグをロック処理に送る。
'   data=Vertices(0)                    このパラメータは Any 型である。これを使用するには、
'                          配列内の先頭要素を送る。

D3DVertexBuffer8SetData g_VB, 0, VertexSizeInBytes * 3, 0, Vertices(0)

頂点バッファ メモリは、柔軟な頂点フォーマットで指定された頂点の単純な配列である。頂点フォーマットに存在するテクスチャ座標の数は、D3DFVF_TEXn フラグで記述される (n は 0 ～ 8 までの値)。その数だけあるテクスチャ座標で必要となるメモリを計算するには、テクスチャ座標セットの数にテクスチャ座標 1 セット分 (1 ～ 4 つの浮動小数) のサイズを乗ずる。

パフォーマンスの注意 D3DUSAGE_WRITEONLY フラグで頂点バッファを作成した場合、D3DLOCK_READONLY ロッキング フラグは使用できない。アプリケーションが頂点バッファ メモリから読み出しのみを行う場合は、D3DLOCK_READONLY フラグを使用する。このフラグを含めると、Direct3D が内部手順を最適化するので効率が上がる。ただし、メモリへのアクセスは読み出し専用になる。

Lock メソッドの Flags パラメータに D3DLOCK_DISCARD または D3DLOCK_NOOVERWRITE を使用する方法の詳細については、「動的な頂点およびインデックス バッファの使い方」を参照すること。

頂点バッファの内容のロック、読み出し、ロックの解除を行うには、D3DVertexBuffer8GetData ヘルパー関数を使用する。


頂点の処理

頂点バッファでの頂点処理は、デバイスの現在のトランスフォーム行列に適用できる。オプションで、ライティング、クリップ フラグの生成、範囲の更新などの頂点処理も適用できる。説明するトピックは、次のとおりである。

  • 固定機能による頂点処理
  • プログラムによる頂点処理


固定機能による頂点処理

ここでは、固定機能による頂点処理について説明する。説明するトピックは、次のとおりである。

  • 固定機能による頂点処理について
  • 転送先頂点バッファの FVF 使用設定


固定機能による頂点処理について

固定機能頂点パイプラインでは、頂点バッファでの頂点処理は、デバイスの現在のトランスフォーム行列に適用でき、オプションで、ライティング、クリップ フラグの生成、および範囲の更新などの頂点処理も適用できる。固定機能による頂点処理を使用する場合、転送先頂点バッファの要素の修正処理は D3DPV_DONOTCOPYDATA フラグによって制御される。このフラグは、固定機能による頂点処理のみに適用できる。Direct3DDevice8 クラスは、頂点処理用の Direct3DDevice8.ProcessVertices メソッドを公開する。頂点シェーダの頂点を入力データ ストリーム セットに処理し、ProcessVertices メソッドを呼び出して 1 つのインターリーブされた頂点データのストリームを生成する。このメソッドは、メソッドがターゲットとする頂点の位置と量、転送先頂点バッファ、および処理オプションを記述する 5 つのパラメータを受け取る。呼び出し後、処理された頂点データは転送先バッファに格納される。

第1 パラメータ SrcStartIndex、第 2 パラメータ DestIndex、第 3 パラメータ VertexCount は、それぞれ、最初にロードされる頂点のインデックス、頂点が配置される転送先頂点バッファのインデックス、処理して転送先バッファに配置する頂点の総数を示す。第 4 パラメータ DestBuffer は、転送元頂点を受け取る頂点バッファ オブジェクトの Direct3DVertexBuffer8 に設定する。SrcStartIndex は、メソッドが頂点の処理を開始するインデックスを指定する。

最後のパラメータ Flags は、メソッドの特殊な処理オプションを指定する。このパラメータを 0 に設定すると、デフォルトの頂点処理が実行され、D3DPV_DONOTCOPYDATA を設定すると、何らかの状況において処理が最適化される。Flags を 0 に設定したときは、頂点処理の影響を受けない転送先頂点バッファの頂点フォーマットの頂点の成分は、頂点シェーダからコピーするか、0 に設定される。ただし、D3DPV_DONOTCOPYDATA を使用すると、Microsoft® Direct3D® によって色および座標情報が生成されない限り、ProcessVertices によって色および座標情報は上書きされない。ライティングが有効、つまり D3DRS_LIGHTING が TRUE のときは、ディフューズ色が生成される。ライティングが有効でスペキュラが有効、つまり D3DRS_SPECULARENABLE および D3DRS_LIGHTING が TRUE のときは、スペキュラ色が生成される。スペキュラ色は、フォグが有効のときも生成される。テクスチャ座標は、テクスチャ トランスフォームまたはテクスチャ生成が有効のときに生成される。ProcessVertices は、現在のレンダリング ステートを使用して、実行する頂点処理を決定する。

デバイスによる頂点処理の制限を判定するには、D3DCAPS8 構造体の VertexProcessingCaps メンバに、サポートする頂点処理能力を問い合わせる。


転送先頂点バッファの FVF 使用設定

Direct3DDevice8.ProcessVertices メソッドでは、転送先頂点バッファの柔軟な頂点フォーマット フラグに対して特殊な設定が必要となる。柔軟な頂点フォーマット (FVF) の使用設定には、頂点処理の現在の設定との互換性がなければならない。

固定機能による頂点処理の場合、ProcessVertices は以下のような FVF 設定を必要とする。

  • 位置座標のタイプは常に D3DFVF_XYZRHW であり、D3DFVF_XYZ および D3DFVF_XYZB1 ～ D3DFVF_XYZB5 は無効である。
  • D3DFVF_NORMAL、D3DFVF_RESERVED0、および D3DFVF_RESERVED2 フラグは設定しない。
  • 以下の条件の OR 演算子が TRUE を返す場合、D3DFVF_DIFFUSE フラグを設定する必要がある。
    • ライティングが有効、つまり D3DRS_LIGHTING が TRUE である。
    • ライティングが無効で、入力頂点ストリームにディフューズ色があり、D3DPV_DONOTCOPYDATA が設定されていない。
  • 以下の条件の OR が TRUE を返す場合、D3DFVF_SPECULAR フラグを設定する必要がある。
    • ライティングが有効でスペキュラ色が有効、つまり D3DRS_SPECULARENABLE が TRUE である。
    • ライティングが無効であり、入力頂点ストリームにスペキュラ色が存在し、D3DPV_DONOTCOPYDATA が設定されていない。
    • 頂点フォグが有効、つまり D3DRS_FOGVERTEXMODE が D3DFOG_NONE に設定されていない。

また、テクスチャ座標のカウント数は、以下の方法で設定する。

  • すべてのアクティブ テクスチャ ステージに対して、テクスチャ トランスフォームとテクスチャ生成が無効の場合、D3DPV_DONOTCOPYDATA は設定されず、出力テクスチャ座標の数およびタイプは、入力テクスチャ座標の数およびタイプと一致しなければならない。D3DPV_DONOTCOPYDATA が設定されていて、テクスチャ トランスフォームとテクスチャ生成が無効な場合、出力テクスチャ座標は無視される。
  • いずれかのアクティブ テクスチャ ステージに対して、テクスチャ トランスフォームまたはテクスチャ生成が有効になっている場合、出力される頂点は入力された頂点よりも多くのテクスチャ座標を必要とすることがある。これは、テクスチャ生成によって生成されたりテクスチャ トランスフォームによって派生したテクスチャ座標による、テクスチャ座標の増殖によるものである。DrawPrimitive 呼び出しでも同様の増殖が発生するが、この場合はアプリケーション プログラマからは見えないことに注意すること。このケースでは、Microsoft® Direct3D® によって新しいテクスチャ座標セットが生成される。テクスチャ ステージが進み、テクスチャ生成、テクスチャ トランスフォーム、テクスチャ座標インデックスの設定を分析して、そのステージに固有のテクスチャ座標セットが必要かどうかを判定するにつれて、新しいテクスチャ座標セットが生成される。新しいセットが必要になるたびに、追加された順に割り当てられる。最大の、そして一般的な必要数は 1 ステージあたり 1 セットであるが、D3DTSS_TEXCOORDINDEX を介して未トランスフォームのテクスチャ座標を共有することによって、これより少ない場合もある。

つまり、テクスチャがそのステージにバインドされていて、以下の条件のいずれかが TRUE の場合、各テクスチャ ステージには、新しいテクスチャ座標セットが生成される。

  • そのステージのテクスチャ生成が有効である。
  • そのステージのテクスチャ トランスフォームが有効である。
  • 未トランスフォームの入力テクスチャ座標が、D3DTSS_TEXCOORDINDEX を介して初めて参照される。

Direct3D がテクスチャ座標を生成するとき、アプリケーションは以下のアクションを実行する必要がある。

  1. 適切な FVF 使用で転送先頂点バッファを使用する。
  2. 処理後のテクスチャ座標の配置に応じて、テクスチャ ステージの D3DTSS_TEXCOORDINDEX を再プログラムする。処理した頂点バッファを、その後の Direct3DDevice8.DrawPrimitive 呼び出しや Direct3DDevice8.DrawIndexedPrimitive 呼び出しで使用すると、D3DTSS_TEXCOORDINDEX 設定が再プログラムされることに注意すること。

最後に、テクスチャ座標のサイズ (D3DFVF_TEX0 ～ D3DFVF_TEX8) は、以下のように設定しなければならない。

  • 各テクスチャ座標セットに対するテクスチャ トランスフォームおよびテクスチャ生成が無効の場合、出力テクスチャ座標のサイズは入力と一致しなければならない。テクスチャ トランスフォームが有効の場合、出力のサイズは D3DTTFF_COUNT1、D3DTTFF_COUNT2、D3DTTFF_COUNT3、または D3DTTFF_COUNT4 によって定義されるカウントと一致しなければならない。テクスチャ トランスフォームが無効でテクスチャ生成が有効の場合、出力のサイズは、テクスチャ生成モードの設定に一致しなければならない。現在のところ、すべてのモードで 3 つの float 型の値が生成される。

転送先頂点バッファの FVF コードと互換性がないために ProcessVertices が失敗した場合、デバッグ出力に互換性を持つコードが出力される (デバッグ ビルドのみ)。


プログラムによる頂点処理

プログラムされた頂点シェーダを使用するときは、転送先頂点バッファで更新された要素は、シェーダ関数プログラムによって制御される。アプリケーションが転送先頂点のいずれかのレジスタに書き込みを行うと、転送先頂点バッファの各頂点内の対応する要素が更新される。アプリケーションが書き込みを行わなかった転送先頂点バッファ内の要素は、修正されない。アプリケーションが転送先頂点バッファに存在しない要素に書き込みを行うと、Direct3DDevice8.ProcessVertices は失敗する。


頂点バッファからのレンダリング

頂点バッファから頂点データをレンダリングするには、いくつかのステップが必要である。まず、Direct3DDevice8.SetStreamSource メソッドを呼び出して、ストリーム ソースを設定する必要がある。次のコードに例を示す。

Call m_D3Device.SetStreamSource(0, VB, len(CUSTOMVERTEX))

SetStreamSource の第 1 パラメータは、Direct3D にデバイス データ ストリームのソースを知らせる。第 2 パラメータは、データ ストリームにバインドする頂点バッファである。第 3 パラメータは、成分のサイズをバイト単位で指定する。上のサンプル コードでは、CUSTOMVERTEX のサイズが成分のサイズに使用される。

次のステップでは、Direct3DDevice8.SetVertexShader メソッドを呼び出して、使用する頂点シェーダを Direct3D に知らせる。次のサンプル コードでは、FVF コードを頂点シェーダに設定している。これにより、処理する頂点のタイプを Direct3D に知らせる。

Call m_D3DDevice.SetVertexShader(D3DFVF_CUSTOMVERTEX)

ストリーム ソースおよび頂点シェーダを設定した後、描画メソッドで頂点バッファを使用する。次のコードは、Direct3DDevice8.DrawPrimitive メソッドを使用して、頂点バッファから頂点をレンダリングする方法を示している。

Call m_D3DDevice.DrawPrimitive(D3DPT_TRIANGLELIST, 0, 1)

DrawPrimitive が受け取る第 2 パラメータは、ロードする頂点バッファにある最初のベクトルのインデックスである。


頂点バッファの記述の取得

Direct3DVertexBuffer8.GetDesc メソッドを呼び出して、頂点バッファに関する情報を取得する。このメソッドは、頂点バッファに関する情報を D3DVERTEXBUFFER_DESC 構造体のメンバに格納する。


インデックス バッファ

ここでは、Microsoft® Direct3D® アプリケーションにおいてインデックス バッファを理解し、使用するのに必要な概念を説明する。説明するトピックは、次のとおりである。

  • インデックス バッファとは
  • インデックス バッファの記述
  • インデックス バッファのプールと使用
  • デバイスの種類とインデックス処理の要件
  • インデックス バッファの使い方


インデックス バッファとは

インデックス バッファとは、Direct3DIndexBuffer8 クラスで表される、インデックス データを保持するメモリ バッファである。インデックス データ、つまりインデックスは、頂点バッファへの整数オフセットであり、Direct3DDevice8.DrawIndexedPrimitive メソッドを呼び出すと、プリミティブのレンダリングで使用される。


インデックス バッファの記述

インデックス バッファは、能力の点から記述される。インデックス バッファは、システム メモリ内にだけ存在できるのか、書き込み操作だけに使用されるのか、インデックス バッファが含むことができる頂点の種類と数などが記述される。これらの特性はすべて D3DINDEXBUFFER_DESC 型に保持される。

インデックス バッファの記述によって、既存バッファが作成された方法がアプリケーションに知らされる。システムが作成済みインデックス バッファの能力を書き込めるように、空白の記述構造体を用意する。このタスクの詳細については、「インデックス バッファの記述の取得」を参照すること。

Format メンバは、インデックス バッファ データのサーフェス フォーマットを記述する。

Type は、インデックス バッファのリソース タイプを識別する。

Usage 構造体のメンバは、一般的な能力フラグを格納する。D3DUSAGE_SOFTWAREPROCESSING フラグは、そのインデックス バッファがソフトウェア頂点処理に使用されることを示す。Usage に D3DUSAGE_WRITEONLY フラグを指定すると、インデックス バッファ メモリは書き込み処理のみに使用される。これによりドライバは解放され、高速処理と高速レンダリングを可能にする最適なメモリ位置にインデックス データが配置される。D3DUSAGE_WRITEONLYフラグが使用されていない場合、ドライバは読み出し処理に効率の悪い位置にデータを配置しなくなる。れにより、処理速度やレンダリング速度が多少犠牲になる。このフラグが指定されていない場合、アプリケーションはインデックス バッファ内のデータで読み書き処理を実行すると見なされる。

Pool は、インデックス バッファに割り当てられるメモリ クラスを指定する。D3DPOOL_SYSTEMMEM フラグは、システムがシステム メモリ内にインデックス バッファを作成したことを示す。

Size メンバは、単にインデックス バッファ データのサイズをバイト数で格納する。


インデックス バッファのプールと使用

インデックス バッファは、Direct3DDevice8.CreateIndexBuffer メソッドで作成する。このメソッドは、プール (メモリ クラス) パラメータと使用パラメータを取る。

D3DUSAGE_SOFTWAREPROCESSING フラグは、そのデバイスに対してミックス モードまたはソフトウェア頂点処理 (D3DCREATE_MIXED_VERTEXPROCESSING / D3DCREATE_SOFTWARE_VERTEXPROCESSING) が有効になっているときに設定できる。D3DUSAGE_SOFTWAREPROCESSING は、ミックス モードでのソフトウェア頂点処理に使用するバッファに設定し、ミックス モードでのハードウェア頂点処理 (D3DCREATE_HARDWARE_VERTEXPROCESSING) 時に最高のパフォーマンスを得ようとするときには設定してはならない。ただし、単一のバッファをハードウェアおよびソフトウェア頂点処理の両方に使用する場合は、D3DUSAGE_SOFTWAREPROCESSING を設定することが唯一のオプションである。D3DUSAGE_SOFTWAREPROCESSING は、ミックスおよびソフトウェア デバイスで使用できる。

インデックス処理がハードウェアで実行される場合でも、D3DPOOL_SYSTEMMEM を指定すれば、頂点バッファとインデックス バッファをシステム メモリ内に強制的に配置することができる。これは、ドライバによってこれらのバッファが AGP メモリに入れられたときに、ページ ロックされるメモリが多くなりすぎないようにする方法である。


デバイスの種類とインデックス処理の要件

インデックス処理のパフォーマンスは、インデックス バッファのメモリ内での位置と、使用されるレンダリング デバイスの種類に大きく依存する。インデックス バッファを作成すると、アプリケーションはそのインデックス バッファへのメモリ割り当てを制御する。D3DPOOL_SYSTEMMEM メモリ フラグが設定されているときは、システム メモリ内にインデックス バッファが作成される。D3DPOOL_DEFAULT メモリ フラグを使用すると、インデックス バッファ用のメモリの最良の割り当て場所をデバイス ドライバが決定し、このようにして決定されたメモリのことを多くの場合、ドライバ最適化メモリと呼ぶ。ドライバ最適化メモリとしては、ローカル ビデオ メモリ、非ローカル ビデオ メモリ、またはシステム メモリが指定される。

Direct3DDevice8.CreateIndexBuffer メソッドを呼び出すときに、D3DUSAGE_SOFTWAREPROCESSING 動作フラグを設定すると、インデックス バッファはソフトウェア頂点処理に使用される。ソフトウェア頂点処理を使用する場合、このフラグはミックス モードの頂点処理 (D3DCREATE_MIXED_VERTEXPROCESSING) で必要となる。

アプリケーションは、ドライバ最適化メモリに割り当てられたインデックス バッファに頂点を直接書き込むことができる。この方法により、以降の冗長なコピー処理を防止する。ただし、ドライバ最適化メモリからホストによって実行される読み取り処理は低速な場合があるため、アプリケーションがインデックス バッファからデータを読み返すときには、この方法はうまく機能しない。したがって、アプリケーションで処理中に読み取り、またはバッファへのデータ書き込みを不規則に実行する必要がある場合は、システム メモリにインデックス バッファを割り当てるとよい。

注 ドライバが頂点バッファまたはインデックス バッファを AGP メモリに配置する場合に、ビデオ メモリまたは大量のページロック RAM を拡張しないときを除いては、常に D3DPOOL_DEFAULT を使用する。


インデックス バッファの使い方

ここでは、インデックス バッファを処理する際にアプリケーションが実行する一般的なタスクについて説明する。説明するトピックは、次のとおりである。

  • インデックス バッファの作成
  • インデックス バッファの内容へのアクセス
  • インデックス バッファからのレンダリング
  • インデックス バッファの記述の取得


インデックス バッファの作成

Direct3DDevice8.CreateIndexBuffer メソッドを呼び出して、インデックス バッファ オブジェクトを作成する。このメソッドは、5 つのパラメータを受け取る。第 1 パラメータは、インデックス バッファの長さをバイト単位で指定する。

第 2 パラメータは、使用コントロール セットである。特に、この値は、インデックスによって参照される頂点がクリッピング情報を格納できるかどうかを指定する。パフォーマンスを向上させるには、クリッピングの必要がないときに D3DUSAGE_DONOTCLIP を指定する。

第 3 パラメータは、各インデックスのサイズを指定する CONST_D3DFORMAT 列挙型の D3DFMT_INDEX16 または D3DFMT_INDEX32 メンバのいずれかである。

第 4 パラメータは、新しいインデックス バッファをメモリ内のどの位置に配置するかを指示する CONST_D3DPOOL 列挙型のメンバである。

次の Visual Basic のコードは、インデックス バッファの作成方法を示している。

'
' この例では、変数 m_D3DDevice は
' Direct3DDevice オブジェクトによって公開される IDirect3DDevice8 インターフェイスである。
' IB は Direct3DIndexBuffer8 型の変数である。
'

Set IB = m_D3DDevice.CreateIndexBuffer(16834, D3DUSAGE_WRITEONLY,
                                       D3DFMT_INDEX16, D3DPOOL_DEFAULT)


インデックス バッファの内容へのアクセス

インデックス バッファを使用すると、Microsoft® Visual Basic® アプリケーションでは、インデックス バッファ内のインデックス データを簡単に更新できる。インデックス バッファをロック、設定、およびロック解除するには、D3DIndexBuffer8SetData ヘルパー関数を使用する。D3DVertexBuffer8SetData は、5 つのパラメータを受け取る。第 1 パラメータ Ibuffer は、インデックス データを格納する Direct3DIndexBuffer8 オブジェクトである。第 2 パラメータ Offset は、インデックス データへのオフセットである。第 3 パラメータは、インデックス データのサイズをバイト単位で示す。

第 4 パラメータ Flags は、メモリのロック方法をシステムに知らせる。このパラメータを使って、バッファ内のデータにアプリケーションがどのようにアクセスするかを示すことができる。アプリケーションがインデックス データにアクセスする方法に応じて、Flags パラメータに定数を指定する。これにより、ドライバはメモリをロックして、要求されているアクセス タイプでの最高のパフォーマンスを提供する。アプリケーションがインデックス バッファ メモリから読み出しのみを行う場合は、D3DLOCK_READONLY フラグを使用する。このフラグを含めると、Microsoft® Direct3D® が内部手順を最適化するので効率が上がる。ただし、メモリへのアクセスは読み出し専用になる。

D3DIndexBuffer8SetData ヘルパー関数が受け取る最後のパラメータ Data は、インデックス バッファにロードするデータの配列の最初の要素である。このパラメータは Any 型である。このパラメータを正しく使用するためには、Data に配列の最初の要素を指定する必要がある。次のコードに例を示す。

Dim Indices(2) As CUSTOMINDEX
Dim IndexSizeInBytes As Long

' インデックス データの長さを決定する。
IndexSizeInBytes = Len(Indices(0))

' インデックス バッファにインデックスをコピーする。
D3DIndexBuffer8SetData VB, 0, IndexSizeInBytes * 3, 0, Indices(0)

注 D3DUSAGE_WRITEONLY フラグでインデックス バッファを作成した場合、D3DLOCK_READONLY ロッキング フラグは使用できない。アプリケーションがインデックス バッファ メモリから読み出しのみを行う場合は、D3DLOCK_READONLY フラグを使用する。このフラグを含めると、Direct3D が内部手順を最適化するので効率が上がる。ただし、メモリへのアクセスは読み出し専用になる。

Lock メソッドの Flags パラメータに D3DLOCK_DISCARD または D3DLOCK_NOOVERWRITE を使用する方法の詳細については、「動的な頂点およびインデックス バッファの使い方」を参照すること。

インデックス バッファの内容をロック、読み出す、およびロック解除するには、D3DIndexBuffer8GetData ヘルパー関数を使用する。


インデックス バッファからのレンダリング

インデックス バッファのインデックス データをレンダリングするには、いくつかのステップが必要である。まず、Direct3DDevice8.SetStreamSource メソッドを呼び出して、ストリーム ソースを設定する必要がある。

Call m_D3DDevice.SetStreamSource( 0, VB, len(CUSTOMVERTEX) )

SetStreamSource の第 1 パラメータは、Direct3D にデバイス データ ストリームのソースを知らせる。第 2 パラメータは、データ ストリームにバインドする頂点バッファである。第 3 パラメータは、成分のサイズをバイト単位で指定する。上のサンプル コードでは、CUSTOMVERTEX のサイズが成分のサイズに使用されている。

次のステップでは、Direct3DDevice8.SetIndices メソッドを呼び出してインデックス データのソースを設定する。

Call m_D3DDevice.SetIndices( IB, 0 )

SetIndices が受け取る最初のパラメータは、設定するインデックス バッファのアドレスである。第 2 パラメータは、頂点ストリームの開始点である。

ストリームおよびインデックス ソースを設定した後、Direct3DDevice8.DrawIndexedPrimitive メソッドを使用して、インデックス バッファからインデックスを使用する頂点をレンダリングする。

Call m_D3DDevice->DrawIndexedPrimitive( D3DPT_TRIANGLELIST, _
                                      0, dwVertices, 0, dwIndices / 3)

DrawPrimitive が受け取る第 2 パラメータは、この呼び出しの間に使用される頂点群に対する最小の頂点インデックスである。第 3 パラメータは、この呼び出しで使用されるインデックスの数である (BaseVertexIndex + MinIndex から始まる)。第 4 パラメータは、インデックス バッファ内におけるインデックスの読み出し開始位置である。DrawPrimitive が受け取る最後のパラメータは、レンダリングするプリミティブの個数である。このパラメータは、プリミティブ カウントおよびプリミティブ タイプの関数である。上のコードでは、三角形を使用している。したがって、レンダリングするプリミティブの個数は、3 で割り切れるインデックス数となる。


インデックス バッファの記述の取得

Direct3DIndexBuffer8.GetDesc メソッドを呼び出して、インデックス バッファに関する情報を取得する。このメソッドは、D3DINDEXBUFFER_DESC 構造体のメンバに頂点バッファに関する情報を設定する。


テクノロジと特殊効果

Microsoft® Direct3D® は、3D シーンをよりリアルに表示するための強力なツール セットを提供する。ここでは、Direct3D で生成できる一般的な特殊効果について説明する。使用できる効果は、ここに掲載するものに限らない。説明するトピックは、次のとおりである。

  • アルファ ブレンディング
  • アンチエイリアシング
  • バンプ マッピング
  • 環境マッピング
  • フォグ
  • ジオメトリ ブレンディング
  • インデックス付き頂点ブレンディング
  • ステンシル バッファ技術
  • 頂点トゥイーニング
  • カラー ライティング


アルファ ブレンディング

アルファ ブレンディングは、透明または半透明ピクセルを含む画像を表示するために使用される。赤、緑、および青のカラー チャネルのほか、アルファ ビットマップ内の各ピクセルには、アルファ チャネルと呼ばれる透明成分がある。アルファ チャネルには、一般的にカラー チャネルと同じ数だけのビットが含まれる。たとえば、8 ビット アルファ チャネルの場合、0 (ピクセル全体が透明) ～ 255 (ピクセル全体が不透明) まで、256 レベルの透明を表現できる。次の一覧は、アルファ ブレンディングを使用して作成できる特殊効果のいくつかを示している。

  • ビルボーディング
  • 雲、煙、蒸気
  • 火、炎、爆発


ビルボーディング

3D シーンを作成するとき、2D オブジェクトを 3D オブジェクトであるかのように表示することによってパフォーマンスを向上できることがある。この考え方が、ビルボード処理技術の基になっている。

通常の意味でのビルボードは、道路沿いの掲示板のことである。Microsoft® Direct3D® アプリケーションでは、矩形ソリッドを定義してテクスチャを適用することで、このようなビルボードを簡単に作成およびレンダリングできる。3D グラフィックスでの特殊な意味でのビルボードは、これを拡張したものである。この意味でのビルボード処理の目的は、2D オブジェクトを 3D オブジェクトのように見せることである。この手法では、オブジェクトのイメージを保持するテクスチャを矩形プリミティブに適用する。このプリミティブは、正面が常にユーザーの方を向くように回転される。このプリミティブは、正面が常にビューアの方を向くように回転される。このオブジェクトの画像は矩形でなくても問題ない。ビルボードの部分を透明にして、表示したくないビルボード画像の部分を不可視にすることができる。

多くのゲームでは、アニメーションしたスプライトにビルボード処理を使用している。たとえば、ユーザーが 3D の迷路を移動するとき、収集できる武器や褒美が表示される。これらは、矩形プリミティブにテクスチャを適用した典型的な 2D 画像である。ビルボード処理は、ゲームで木、潅木、および雲の画像をレンダリングするために使用されることが多い。

ビルボードに画像を適用するときは、最初に、正面がユーザーの方を向くように矩形プリミティブを回転しなければならない。次に、このプリミティブを配置場所に平行移動しなければならない。その後、このプリミティブにテクスチャを適用できる。

ビルボード処理は、対称的なオブジェクト、特に垂直軸に対して対称的なオブジェクトの処理に最適である。また、ビルボード処理には、視点の高さがあまり上がらないことが必要である。ユーザーがビルボードを上から見ることが許されている場合、そのオブジェクトが 3D ではなく 2D であることがすぐにわかってしまう。


雲、煙、蒸気

雲、煙、蒸気のたなびきもすべて、ビルボード処理技術を拡張して作成できる。詳細については、「ビルボーディング」を参照すること。1 つの軸ではなくて 2 つの軸を中心にビルボードを回転することで、ユーザーがビルボードをどの角度からでも見ることができる。通常、アプリケーションでは水平軸と垂直軸を中心にビルボードを回転する。

簡単な雲を作成するには、プリミティブの面がユーザーの方を向くように 1 つまたは 2 つの軸を中心に矩形プリミティブを回転させる。次に、雲のようなテクスチャを透明度と共にこのプリミティブに適用する。透明度のあるテクスチャのプリミティブへの適用の詳細については、「テクスチャ ブレンディング」を参照すること。雲をアニメーションするには、一連のテクスチャを時間の経過につれて適用する。

プリミティブのグループで雲を作れば、さらに複雑な雲を作成できる。この場合、雲の各部分が矩形プリミティブになる。これらのプリミティブをそれぞれ独立して連続的に移動して、動的な霧のように見せることができる。次の図にこれを示す。

煙は、雲と同様の方法で表示する。通常、煙では複雑な雲のように複数のビルボードが必要である。煙は時間と共にうねったり上昇するので、立ち昇る煙を形成するビルボードを移動させる必要がある。煙が上昇したり消散するときは、ビルボードの追加が必要な場合もある。

蒸気のたなびきは、上昇しない煙のようなものである。ただし、蒸気は煙のように徐々に消散する。次の図は、蒸気のたなびきをシミュレートするためにビルボードを使用する技術を示している。


火、炎、爆発

Microsoft® Direct3D® を使用して、エネルギーを発する自然現象をシミュレーションできる。たとえば、炎のようなテクスチャをビルボード セットに適用して、火を表現できる。これが特に効果的なのは、火のテクスチャを連続的に使用して、燃えるビルボードそれぞれの上の炎をアニメーションする場合である。ビルボードごとにアニメーション再生の速度を変えると、炎のリアリティが増す。混じり合った 3D の炎に見せるには、ビルボードを重ね合わせ、ビルボード上のテクスチャを重ね合わせればよい。

炎や閃光は、シーン内のすべてのプリミティブに対して、徐々に明るくなるライト マップを適用することでシミュレーションできる。これはオーバーヘッドの高い技術であるが、局所的な炎や閃光のシミュレーションは可能である。つまり、炎や閃光を発するシーンを最初に明るくすることができる。

ほかの技術としては、レンダリング ターゲット領域全体を覆うようにシーンの前面にビルボードを配置する方法がある。アプリケーションで、連続的に白くなるテクスチャをビルボードに適用し、徐々に透明度を減少させる。時間と共にシーン全体が白くなる。これは、炎を作成する方法としてはオーバーヘッドの低い方法である。しかし、この技術を使用すると、単一のポイント ライトの光源から明るい閃光を表現することが困難になることがある。

爆発は、火、閃光、および炎で使用したような 3D シーンの作成方法によって表示できる。たとえば、アプリケーションでビルボードを使用して、爆発の衝撃波や噴煙を表示できる。同時に、ビルボード セットを使用して炎をシミュレートできる。さらに、シーンの前面に単一のビルボードを配置して、シーン全体に閃光を追加できる。

エネルギー ビームは、ビルボードを使用してシミュレーションできる。また、線リストまたは線ストリップとして定義したプリミティブを使用してもこのビームを表示できる。詳細については、「線リスト」および「線ストリップ」を参照すること。

ビルボードや三角形リストとして定義したプリミティブを使用して、電磁力界を作成できる。三角形リストから電磁力界を作成するには、電磁力界の範囲と同じ空間を占める三角形リストにある分離した三角形のセットを定義すること。ユーザーは、三角形どうしの隙間から三角形の背後のシーンを見ることができ、あたかも電磁力界を見ているかのように感じられる。三角形がエネルギーで輝いているように見せるテクスチャを三角形リストに適用する。詳細については、「三角形リスト」を参照すること。


アンチエイリアシング

アンチエイリアシングとは、正確に水平または垂直でない線を描いたときに現れる階段状のピクセルを減らすための技法である。3 次元シーンの場合、この不自然な効果は異なる色のポリゴン間の境界線上でもっとも目立つ。アンチエイリアシングは、ピクセルを効果的に境界線上でブレンドして、シーンの外観をより自然にする。

Microsoft® Direct3D® がサポートするアンチエイリアシングの方法には、エッジ アンチエイリアシングおよびフルシーン アンチエイリアシングの 2 種類がある。どちらのアンチエイリアシングがアプリケーションによいかは、パフォーマンスと視覚的品質の要件に依存する。

  • エッジ アンチエイリアシング
  • フルシーン アンチエイリアシング

次のトピックでは、特殊効果を使ってシミュレートする方法またはアンチエイリアシングの使用方法について説明する。

  • モーション ブラー


エッジ アンチエイリアシング

エッジ アンチエイリアシングでは、シーンをレンダリングした後、オブジェクトの凸状シルエットを再レンダリングして、線にアンチエイリアシングする。システムは辺を再描画し、ぼかして、不自然な効果を減らす。

まず、Direct3D8.GetDeviceCaps メソッドを呼び出して、Microsoft® Direct3D® デバイスがアンチエイリアシングをサポートしているかどうかを調べる。デバイスがエッジ アンチエイリアシングをサポートしている場合は、GetDeviceCaps が RasterCaps の D3DCAPS8 型に D3DPRASTERCAPS_ANTIALIASEDGES フラグを設定する。

デバイスがアンチエイリアシングをサポートしている場合は、D3DRS_EDGEANTIALIAS レンダリング ステートを TRUE に設定する。次のコードに例を示す。

m_D3DDevice.SetRenderState D3DRS_EDGEANTIALIAS, TRUE

次に、Direct3DDevice8.DrawPrimitive および D3DPT_LINESTRIP または D3DPT_LINELIST プリミティブ タイプのいずれかを使用して、シーン内のエッジのみ再描画する。エッジ アンチエイリアシングの動作は、線以外のプリミティブについては定義されていないため、アンチエイリアシングが完了したら、D3DRENDERSTATE_EDGEANTIALIAS を FALSE に設定して機能を確実に無効にする。

シーンの中のすべてのエッジを再描画すると、大きな不自然な効果を生じさせずに済むが、計算量が膨大になる。また、この方法ではどのエッジをアンチエイリアシングするべきか判断が困難なこともある。再描画するのにもっとも重要なエッジは、非常に異なる色の領域の間のエッジ (たとえば影のエッジ)、または非常に異なるマテリアルの間の境界である。ほぼ同じ色の 2 つのポリゴンの間のエッジをアンチエイリアシングすることに意味はないが、計算量は膨大である。このような理由により、現在のハードウェアがフルシーン アンチエイリアシングをサポートしているのであれば、これが好ましいことが多い。詳細については、「フルシーン アンチエイリアシング」を参照すること。


フルシーン アンチエイリアシング

フルシーン アンチエイリアシングとは、シーン内の各ポリゴンのエッジをシングル パスでラスタライズしてぼかすことを指す。2 つ目のパスは必要ない。フルシーン アンチエイリアシングは、サポートされている場合は三角形および三角形のグループにのみ影響する。Microsoft® Direct3D® サービスを使用して線にアンチエイリアシングを適用することはできない。Direct3D では、フルシーン アンチエイリアシングを実行するには、各ピクセルにマルチサンプリングを使用する。マルチサンプリングが有効な場合、ピクセルのすべてのサブサンプルが 1 つのパスで更新されるが、複数のレンダリング パスを含むほかのエフェクトに使用される場合は、アプリケーションでサブサンプルの一部だけが指定のレンダリング パスに影響を受けるよう指定できる。この後者のアプローチによって、モーション ブラー、フィールド フォーカス エフェクトの深度、反射ブラーなどをシミュレートすることができる。

どちらの場合も、ピクセルごとに記録されたさまざまなサンプルがブレンドされ、スクリーンに出力される。このようなアプローチを使用すると、アンチエイリアシングやほかのエフェクトのイメージ品質が向上する。

Direct3D8.CreateDevice メソッドでデバイスを作成する前に、フルシーン アンチエイリアシングがサポートされているかどうかを調べる必要がある。このためには、Direct3D8.CheckDeviceMultiSampleType メソッドを呼び出す。次のコードに例を示す。

'
' このコードでは、D3D は Direct3D8 オブジェクトへの
' 有効なポインタであると仮定している。
'

D3D->CheckDeviceMultiSampleType( D3DADAPTER_DEFAULT,
                                 D3DDEVTYPE_HAL , D3DFMT_R8G8B8,
                                 FALSE, D3DMULTISAMPLE_2_SAMPLES ) ) )

CheckDeviceMultiSampleType が受け取る第 1 パラメータは、問い合わせるディスプレイ アダプタを示す序数である。この例では、D3DADAPTER_DEFAULT を使用してプライマリ ディスプレイ アダプタを指定する。第 2 パラメータは CONST_D3DDEVTYPE 列挙型の値で、デバイスの種類を指定する。第 3 パラメータには、サーフェスのフォーマットを指定する。第 4 パラメータは、フルウィンドウ マルチサンプリング (TRUE) またはフルスクリーン アンチエイリアシング (FALSE) を問い合わせるかどうかを Direct3D に知らせる。この例では FALSE を使用して、フルシーン アンチエイリアシングについて問い合わせることを Direct3D に指示している。最後のパラメータは、テストするマルチサンプリング手法を指定する。CONST_D3DMULTISAMPLE_TYPE 列挙型の値を使用する。この例では、2 つのレベルのマルチサンプリングがサポートされているかどうかをテストする。

デバイスが使用したい 2 つのレベルのマルチサンプリングをサポートしている場合、次の手順は、マルチサンプルのレンダリング サーフェスを作成するために、D3DPRESENT_PARAMETERS 構造体の適切なメンバにデータを設定して、プレゼンテーション パラメータを設定することである。設定した後は、デバイスを作成することができる。次のサンプル コードは、マルチサンプリングのレンダリング サーフェスでデバイスを設定する方法を示している。

'
' 以下のコードでは、pD3D は有効な Direct3D8 オブジェクトであり、
' D3DDevice は有効な Direct3DDevice8 オブジェクトであると仮定している。
'

Dim d3dpp As D3DPRESENT_PARAMETER
d3dpp.Windowed = FALSE
d3dpp.SwapEffect = D3DSWAPEFFECT_DISCARD
d3dpp.MultiSampleType = D3DMULTISAMPLE_2_SAMPLES
Set D3DDevice = pD3D->CreateDevice(D3DADAPTER_DEFAULT, D3DDEVTYPE_HAL, hWnd,
                                   D3DCREATE_SOFTWARE_VERTEXPROCESSING, d3dpp )

注 マルチサンプリングを使用するには、D3DPRESENT_PARAMETER の SwapEffect メンバを D3DSWAPEFFECT_DISCARD に設定する必要がある。

最後の手順は、Direct3DDevice8.SetRenderState メソッドを呼び出して D3DRS_MULTISAMPLEANTIALIAS を TRUE に設定することによって、マルチサンプリングのアンチエイリアシングを有効にすることである。この値に TRUE を設定した後は、レンダリングには必ずマルチサンプリングが適用される。シーンにレンダリングする対象に応じて、マルチサンプリングの有効/無効を切り替えることもできる。


モーション ブラー

3D シーンのオブジェクトの知覚速度は、オブジェクトをぼかし、オブジェクトの背後にオブジェクト画像のぼんやりとした跡を残すことで高めることができる。Microsoft® Direct3D® アプリケーションは、フレームごとにオブジェクトを複数回レンダリングして、これを実現する。

通常、Direct3D アプリケーションはシーンをオフスクリーン バッファにレンダリングすることを思い出してほしい。バッファの内容は、アプリケーションで Direct3DDevice8.Present メソッドを呼び出したときにスクリーンに表示される。Direct3D アプリケーションは、スクリーンにフレームを表示する前にオブジェクトをシーンに複数回レンダリングできる。

アプリケーションで DrawPrimitive メソッドへの呼び出しを複数回行い、同じ 3D オブジェクトを繰り返し渡す。それぞれの呼び出しの前に、オブジェクトの位置座標を少し更新し、ターゲット レンダリング サーフェス上に一連の不鮮明なオブジェクト画像を生成する。オブジェクトが 1 つまたは複数のテクスチャを持っている場合、テクスチャすべてをほとんど透明にしてオブジェクトの最初の画像をレンダリングすると、モーション ブラー エフェクトを高めることができる。オブジェクトをレンダリングするたびに、オブジェクトのテクスチャの透明度が減少する。最終位置座標でオブジェクトをレンダリングするときは、透明度なしでオブジェクトをレンダリングすること。例外は、テクスチャの透明度を必要とするほかのエフェクトにモーション ブラーを追加する場合である。どの場合でも、フレームのオブジェクトの最初の画像が最も透明でなければならない。最後の画像の透明度が最も低くなければならない。

ターゲット レンダリング サーフェスに一連のオブジェクト画像をレンダリングし、残りのシーンもレンダリングしたら、Present メソッドを呼び出してスクリーンにフレームを表示する。

ユーザーがシーンを高速で移動するエフェクトをシミュレーションする場合は、スクリーン全体にモーション ブラーを追加できる。この場合、アプリケーションは、フレームごとにシーン全体を複数回レンダリングする。シーンをレンダリングするたびに、視点を少し移動しなければならない。シーンが非常に複雑な場合、フレームごとのシーンのレンダリング回数が増えるので、高速に移動するシーンほどパフォーマンスが低下するのがユーザーにわかる。


バンプ マッピング

ここでは、Microsoft® Direct3D® で実行するバンプ マッピングについて説明する。以下のトピックでは、バンプ マッピングを紹介し、その主要な概念を特定および定義し、アプリケーションでのバンプ マッピングの使用方法について説明する。

  • バンプ マッピングとは
  • バンプ マップ ピクセル フォーマット
  • バンプ マッピングの公式
  • バンプ マッピングの使い方


バンプ マッピングとは

バンプ マッピングは、少数のポリゴンだけできれいにテッセレーションされたオブジェクトの反射状態をシミュレートする、特殊なスペキュラまたはディフューズ環境マッピングである。次の画像は、C++ の BumpEarth サンプルに基づいて、バンプ マッピングのエフェクトを示している。

左側の地球は、地球の表面の画像でテクスチャ処理され、スペキュラ環境マップが適用されている。右側の地球もまったく同じであるが、バンプ マップが適用されている。2 つ目の地球の画像のポリゴン数は、1 つ目の画像のポリゴン数と変わらない。

Microsoft® Direct3D® のバンプ マッピングでは、開発者はデルタ値による輪郭線の情報を提供することから、バンプ マッピングは、正確にはスペキュラまたはディフューズ環境マップのピクセル単位のテクスチャ座標の補正と記述できる。輪郭線の情報は、システムによって次のテクスチャ ステージの環境マップの u および v テクスチャ座標に適用される。デルタ値は、バンプ マップ サーフェスのピクセル フォーマットで符号化される。詳細については、「バンプ マップ ピクセル フォーマット」を参照すること。

BumpEarth サンプルでは、高度マップを使用して輪郭線データを格納する。サンプルを開始すると、高度マップ内のピクセルが処理されて適切な u および v が計算される。これは、隣接する 4 つのピクセルを基準にした、各ピクセルの相対高度に基づく。

本来、Direct3D では高度マップをサポートしていない。高度マップは、輪郭線データを格納および視覚化するのに便利なフォーマットであるにすぎない。前の画像は高度マップに基づいて作成されたもので、BumpEarth サンプルではこの高度マップを使用して、Direct3D に提供するバンプ マップを生成している。この画像は説明を目的に示したものである。アプリケーションでは輪郭線情報をどのようなフォーマットでも格納でき、また、BumpWaves サンプルのように個々のバンプ マップを生成することもできる。

次は、BumpEarth サンプルで使用する高度マップ画像である。このサンプルでは、これを使用して、バンプ マップ テクスチャのピクセル フォーマットでエンコードされるデルタ値を計算する。

バンプ マッピングは、複数のテクスチャ ブレンディング サービスに完全に依存しており、デバイスは少なくとも 2 つのブレンディング ステージ (1 つはバンプ マップ用、もう 1 つは環境マップ用) をサポートしている必要がある。ベース テクスチャ マップを適用するには、最も一般的な場合、最低 3 つのテクスチャ ブレンディング ステージが要求される。次の図は、テクスチャ ブレンディング カスケードにおける、ベース テクスチャ、バンプ マップ、および環境マップ間の関係を示している。

テクスチャ ステージを適切に用意し、バンプ マッピングを有効にする必要がある。このタスクについては、「バンプ マッピング パラメータの設定」で説明する。


バンプ マップ ピクセル フォーマット

バンプ マップとは、特殊なピクセル フォーマットを使用する IDirect3DTexture8 オブジェクトである。赤、緑、および青の色成分を格納するのではなく、バンプ マップの各ピクセルは、u および v のデルタ値 (Du および Dv) を格納し、輝度 L. を格納するときもある。これらの値は、「バンプ マッピングの公式」で説明するように、システムによって適用される。

バンプ マップ ピクセル フォーマットを指定するには、CONST_D3DFORMAT 列挙型を以下のバンプ マップ ピクセル フォーマットのいずれかに設定する。

フォーマット | 説明
D3DFMT_V8U8 | 16 ビットのバンプマップ フォーマット。
D3DFMT_L6V5U5 | 輝度付きの 16 ビット バンプマップ フォーマット。
D3DFMT_X8L8V8U8 | 輝度付きの 32 ビット バンプマップ フォーマットで、8 ビットは各要素のために確保されている。
D3DFMT_Q8W8V8U8 | 32 ビットのバンプマップ フォーマット。
D3DFMT_V16U16 | 32 ビットのバンプマップ フォーマット。
D3DFMT_W11V11U10 | 32 ビットのバンプマップ フォーマット。

ピクセルの Du および Dv コンポーネントは、-1.0 ～ +1.0 の範囲の符号付きの値である。輝度コンポーネントが使用されている場合、この値は 0 ～ 255 の範囲の符号なし整数値である。

注 バンプ マップ ピクセル フォーマットを選択する前に、特定のフォーマットがサポートされているかどうかを調べる必要がある。詳細については、「バンプ マッピングのサポートの検出」を参照すること。


バンプ マッピングの公式

Microsoft® Direct3D® では、各バンプ マップ ピクセルの Du および Dv コンポーネントに次の公式を適用する。

この公式では、変数 Du および Dv はバンプ マップ ピクセルから直接取得され、出力デルタ値 Du' および Dv' を生成するために 2 × 2 行列でトランスフォームされる。システムでは、この出力値を使用して、次のテクスチャ ステージの環境マップを処理するテクスチャ座標を修正する。トランスフォーム行列の係数は、D3DTSS_BUMPENVMAT00、D3DTSS_BUMPENVMAT10、D3DTSS_BUMPENVMAT01、および D3DTSS_BUMPENVMAT11 テクスチャ ステージ ステートで設定する。

u および v デルタ値のほかにも、システムでは、次のブレンディング ステージの環境マップの色の乗算に使用する輝度を計算できる。

この公式では、L' は計算される出力輝度である。L' は、0.0 と 1.0 を含む 0.0 ～ 1.0 の範囲に固定される。変数 L はバンプ マップ ピクセルから取得される輝度値であり、スケーリング係数 S で乗算され、変数 O の値でオフセットされる。D3DTSS_BUMPENVLSCALE および D3DTSS_BUMPENVLOFFSET テクスチャ ステージ ステートは、公式の変数 S および O の値を制御する。この公式が適用されるのは、バンプ マップを含むステージのテクスチャ ブレンディング処理が D3DTOP_BUMPENVMAPLUMINANCE に設定されている場合のみである。D3DTOP_BUMPENVMAP を使用するときは、L' の値に 1.0 が使用される。

出力デルタ値 Du' および Dv' の計算後、システムでは、これらの値を次のテクスチャ ステージのテクスチャ座標に追加し、選択されている色の輝度を乗算して、ポリゴンに適用する色を生成する。


バンプ マッピングの使い方

ここでは、Microsoft® Direct3D® のバンプ マッピングを使用する際に、アプリケーションで実行する最も一般的なタスクについて説明する。説明するトピックは、次のとおりである。

  • バンプ マッピングのサポートの検出
  • バンプ マップ テクスチャの作成
  • バンプ マッピング パラメータの設定


バンプ マッピングのサポートの検出

Microsoft® Direct3D® デバイスが D3DTOP_BUMPENVMAP または D3DTOP_BUMPENVMAPLUMINANCE のいずれかのテクスチャ ブレンディング処理をサポートしている場合、そのデバイスではバンプ マッピングを実行できる。また、アプリケーションではデバイス能力を調べることで、そのアプリケーションで適切なブレンディング ステージ数 (通常は 3 つ以上) がサポートされ、少なくとも 1 つのバンプ マッピング ピクセル フォーマットが公開されていることを確認する必要がある。

次のコードは、指定された条件によってデバイス機能を調べて、現在のデバイスでのバンプ マッピングのサポートを検出する。

Function SupportsBumpMapping As Bool
{
    Dim d3dCaps As D3DCAPS8

    m_D3DDevice.GetDeviceCaps d3dCaps

    ' このデバイスが 2 つのバンプ マッピング ブレンド処理をサポートしているかどうか。
    If ( d3dCaps.TextureOpsCaps And _
         ( D3DTEXOPCAPS_BUMPENVMAP Or D3DTEXOPCAPS_BUMPENVMAPLUMINANCE ) = 0) Then
         SupportBumpMapping = FALSE
    End If

    ' このデバイスが最大 3 つのブレンディング ステージをサポートしているかどうか。
    If d3dCaps.MaxTextureBlendStages < 3 Then
        SupportBumpMapping = FALSE
    End If

    SupportBumpMapping = TRUE
}


バンプ マップ テクスチャの作成

ほかのテクスチャの場合と同様に、バンプ マップ テクスチャを作成する。アプリケーションでバンプ マッピングのサポートを確認し、有効なピクセル フォーマットを取得したら (「バンプ マッピングのサポートの検出」で説明するように)、バンプ マップ テクスチャ サーフェスを作成できる。テクスチャの作成については、「テクスチャ サーフェス オブジェクトの取得」を参照すること。

サーフェスの作成後は、適切なデルタ値を持つ各ピクセルと、輝度 (サーフェス フォーマットに輝度が含まれる場合) をロードできる。各ピクセル コンポーネントの値については、「バンプ マップ ピクセル フォーマット」で説明する。


バンプ マッピング パラメータの設定

アプリケーションでバンプ マップの作成と各ピクセルの内容の設定が完了したら、バンプ マッピング パラメータを設定してレンダリングの準備を行うことができる。バンプ マッピング パラメータには、必要なテクスチャとそのブレンディング処理や、バンプ マップ自体に対するトランスフォームと輝度の制御などを設定する。

Visual Basic でバンプ マッピング パラメータを設定するには:

  1. ベース テクスチャ マップ (使用されている場合)、バンプ マップ、および環境マップ テクスチャをテクスチャ ブレンディング ステージに設定する。
  2. 各テクスチャ ステージの色およびアルファ ブレンディング処理を設定する。
  3. バンプ マップ トランスフォーム行列を設定する。
  4. 必要に応じて、輝度スケール値およびオフセット値を設定する。

次のコードでは、ベース テクスチャ マップ、バンプ マップ、およびスペキュラ環境マップの 3 つのテクスチャを、適切なテクスチャ ブレンディング ステージに設定する。

' 3 つのテクスチャを設定する。
d3dDevice.SetTexture(0, d3dBaseTexture)
d3dDevice.SetTexture(1, d3dBumpMap)
d3dDevice.SetTexture(2, d3dEnvMap)

テクスチャをブレンディング ステージに設定した後、次のコードで、各ステージのブレンディング処理および引数を準備する。

' バンプ マップ テクスチャを作成する。
' カラー処理および引数を設定してバンプ マッピングを準備する。
' ステージ 0:ベース テクスチャ。
Call d3dDevice.SetTextureStageState(0, D3DTSS_COLOROP, D3DTOP_MODULATE)
Call d3dDevice.SetTextureStageState(0, D3DTSS_COLORARG1, D3DTA_TEXTURE)
Call d3dDevice.SetTextureStageState(0, D3DTSS_COLORARG2, D3DTA_DIFFUSE)
Call d3dDevice.SetTextureStageState(0, D3DTSS_ALPHAOP, D3DTOP_SELECTARG1)
Call d3dDevice.SetTextureStageState(0, D3DTSS_ALPHAARG1, D3DTA_TEXTURE)
Call d3dDevice.SetTextureStageState(0, D3DTSS_TEXCOORDINDEX, 1)

' ステージ 1:バンプ マップ - この例では輝度を使用する。
Call d3dDevice.SetTextureStageState(1, D3DTSS_TEXCOORDINDEX, 1)
Call d3dDevice.SetTextureStageState(1, D3DTSS_COLOROP, D3DTOP_BUMPENVMAPLUMINANCE)
Call d3dDevice.SetTextureStageState(1, D3DTSS_COLORARG1, D3DTA_TEXTURE)
Call d3dDevice.SetTextureStageState(1, D3DTSS_COLORARG2, D3DTA_CURRENT)

' ステージ 2:スペキュラ環境マップ。
Call d3dDevice.SetTextureStageState(2, D3DTSS_TEXCOORDINDEX, 0)
Call d3dDevice.SetTextureStageState(2, D3DTSS_COLOROP, D3DTOP_ADD)
Call d3dDevice.SetTextureStageState(2, D3DTSS_COLORARG1, D3DTA_TEXTURE)
Call d3dDevice.SetTextureStageState(2, D3DTSS_COLORARG2, D3DTA_CURRENT)

ブレンディング処理および引数を設定した後、次のコードで、D3DTSS_BUMPENVMAT00 および D3DTSS_BUMPENVMAT11 テクスチャ ステージ ステートを 1.0 に設定して、2×2 バンプ マッピング行列を単位行列に設定する。行列を単位行列に設定すると、システムでは未修正のバンプ マップのデルタ値が使用されるようになるが、これは必ずしも必要ではない。

' バンプ マッピング行列を設定する。
Call d3dDevice.SetTextureStageStateSingle(1, D3DTSS_BUMPENVMAT00, 1#)
Call d3dDevice.SetTextureStageStateSingle(1, D3DTSS_BUMPENVMAT01, 0#)
Call d3dDevice.SetTextureStageStateSingle(1, D3DTSS_BUMPENVMAT10, 0#)
Call d3dDevice.SetTextureStageStateSingle(1, D3DTSS_BUMPENVMAT11, 1#)

バンプ マッピング処理に輝度 (D3DTOP_BUMPENVMAPLUMINANCE) を含める場合は、輝度制御を設定する必要がある。輝度制御により、次のステージのテクスチャから色を調整する前にシステムが行う輝度の計算方法を設定する詳細については、「バンプ マッピングの公式」を参照すること。

' 輝度制御を設定する。これは、バンプ マップに輝度が含まれている場合、および
' D3DTOP_BUMPENVMAPLUMINANCE テクスチャ ブレンディング処理が使用される場合にのみ
' 必要である。
Call d3dDevice.SetTextureStageStateSingle(1, D3DTSS_BUMPENVLSCALE, 0.5)
Call d3dDevice.SetTextureStageStateSingle(1, D3DTSS_BUMPENVLOFFSET, 0#)

アプリケーションでバンプ マッピング パラメータを設定した後は、通常どおりにレンダリングを実行でき、レンダリングされるポリゴンにバンプ マッピング エフェクトが適用される。

注 この例では、パラメータはスペキュラ環境マッピング用に設定されている。ディフューズ ライト マッピングを行う場合は、最後のステージのテクスチャ ブレンディング処理を D3DTOP_MODULATE に設定する。詳細については、「ディフューズ ライト マップ」を参照すること。


環境マッピング

ここでは、Microsoft® Direct3D® の一般的な 2 種類の環境マッピングの実行について説明する。グラフィックス業界では多種多様な環境マッピングが使用されているが、以下のトピックでは、最も一般的なキューブ環境マップおよび球状環境マッピングについて説明する。

  • 環境マッピングとは
  • キューブ環境マップ
  • 球状環境マッピング


環境マッピングとは

環境マッピングとは、反射性の高いサーフェスをレイ トレーシングを使用せずにシミュレートする方法である。実際、環境マッピングでは、オブジェクトの周囲の景色を含む特殊なテクスチャ マップがそのオブジェクト自体に適用される。その結果、反射性を持つサーフェスには、十分に人の目をごまかせる程度に周囲の景色が映り込む。レイ トレーシングを実行した場合に生じる計算負荷も発生しない。

次の画像は、C++ の SphereMap サンプルのものである。名前からわかるように、このサンプルでは球状環境マッピングと呼ばれる環境マッピングを使用している。詳細については、「球状環境マッピング」を参照すること。

このティーポットは周囲の景色を反射しているように見えるが、実際にはテクスチャが適用されている。環境マッピングは、テクスチャ (特殊な計算で求めたテクスチャ座標を組み合わせたもの) を使用するため瞬時に実行される。


キューブ環境マップ

キューブ環境マップでは、オブジェクトの周囲の空間またはライティングのエフェクトがそのオブジェクトの表面に沿って適用される。これは立方体の内部の 6 つの面によって表現される。説明するトピックは、次のとおりである。

  • キューブ環境マップとは
  • キューブ環境マップ サーフェスの作成
  • キューブ環境マップ サーフェスへのアクセス
  • キューブ環境マップのミップマップ化
  • キューブ環境マップへのレンダリング
  • キューブ環境マップのテクスチャ座標


キューブ環境マップとは

キューブ環境マップ (キューブ マップとも呼ばれる) とは、オブジェクトの周囲のシーンをオブジェクトが立方体の中心にあるかのように表現した画像データを含むテクスチャである。キューブ環境マップの各面は、水平方向と垂直方向の 90°の視野を対象とし、1 つのキューブ マップには 6 つの面がある。各面の向きは、次の図に示すとおりである。

立方体の各面は、ワールド空間の x/y、y/z、または x/z 平面に垂直に位置座標する。次の図は、各平面と面の対応を示している。

キューブ環境マップは、一連のテクスチャ オブジェクトとして実装される。アプリケーションでは、キューブ環境マップに静的な画像を使用したり、キューブ マップの面にレンダリングを行うことで動的な環境マッピングを実行することができる。この場合、キューブ マップ サーフェスは有効なレンダリング ターゲット サーフェスでなければならず、D3DUSAGE_RENDERTARGET フラグ セットで作成されている必要がある。

キューブ マップの各面には、周囲のシーンが緻密にレンダリングされる必要はない。ほとんどの場合、環境マップは湾曲サーフェスに適用される。大部分のアプリケーションで使用する湾曲の度合いが与えられたとすると、結果としてひずんだ画像が生成されるため、環境マップの緻密さはメモリの点からもレンダリングのオーバーヘッドの点からも無駄になる。


キューブ環境マップ サーフェスの作成

キューブ環境マップ テクスチャを作成するには、D3DX8.CreateCubeTexture メソッドを呼び出す。キューブ環境マップ テクスチャは矩形でなければならず、その大きさは 2 の累乗である。

次のコードは、Microsoft® Visual Basic® アプリケーションで単純なキューブ環境マップを作成する方法を示している。

'
' この例では、d3dDevice は有効な Direct3DDevice8 オブジェクトであり、
' g_D3DX は有効な D3DX オブジェクトである。
'
Dim CubeMap As Direct3DCubeTexture8 CubeTexture

Set CubeMap = g_D3DX.CreateCubeTexture( d3dDevice, 256, 1, D3DUSAGE_RENDERTARGET, _
                                        D3DFMT_R8G8B8, D3DPOOL_MANAGED );


キューブ環境マップ サーフェスへのアクセス

Direct3DCubeTexture8.GetCubeMapSurface メソッドを使用してキューブ環境マップのサーフェスからサーフェスに移動できる。

次のコードは、GetCubeMapSurface を使用して、正方向の y 面 (サーフェス 2) のキューブ マップ サーフェスを取得する。

'
' この例では、CubeMap は有効な
' Direct3DCubeTexture8 オブジェクトである。
'
Dim Face2 As Direct3DSurface8

Set Face2 = CubeMap.GetCubeMapSurface( D3DCUBEMAP_FACE_POSITIVE_Y, 0 );

GetAttachedSurface が受け取る第 1 パラメータは、このメソッドで取得する必要があるアタッチされたサーフェスを記述する CONST_D3DCUBEMAP_FACES 列挙型である。第 2 パラメータは、取得するミップマップ化キューブ テクスチャのレベルを Microsoft® Direct3D® に指示する。この場合、このキューブ マップはミップマップ化されていないので、0 が使用される。


キューブ環境マップのミップマップ化

キューブ環境マップはミップマップ化できる。DDSCAPS_MIPMAP 能力を含めると、アタッチされたミップマップ サーフェスのある各サーフェスが作成される。これらのサーフェスの形状は、次の図に示すようになる。

ミップマップ化キューブ環境マップを作成するアプリケーションで各サーフェスにアクセスするには、Direct3DCubeTexture8.GetCubeMapSurface メソッドを呼び出す。D3DCUBEMAP_FACES 列挙型から適切な値を設定して開始する。これについては、「キューブ環境マップ サーフェスへのアクセス」で説明する。次に、Level パラメータを目的のミップマップ レベルに設定して、取得するレベルを選択する。0 は最上位画像に対応することを思い出すこと。


キューブ環境マップへのレンダリング

キューブ マップの個々のサーフェスへは、その他のテクスチャやサーフェス オブジェクトと同じように画像をコピーすることができる。このレンダリングを行う前に実行する最も大切なことは、カメラを正しく配置し、そのサーフェスに対して正しい方向を向くようにトランスフォーム行列を設定することである。正しい方向とは、前方 (+z)、後方 (-z)、左 (-x)、右 (+x)、上方 (+y)、または下方 (-y) である。

次の Microsoft® Visual Basic® コードは、レンダリングするサーフェスに応じて、ビュー行列を用意して設定する。

'
' この例では、CubeMap は有効な Direct3DCubeTexture8 オブジェクトであり、
' m_D3DDevice は有効な Direct3DDevice8 オブジェクトである。
'
Sub RenderFaces

    ' デバイスのトランスフォーム行列を保存する。
    Dim matProjSave As D3DMATRIX, _
        matViewSave As D3DMATRIX
    m_D3DDevice.GetTransform D3DTS_VIEW, matViewSave
    m_D3DDevice.GetTransform D3DTS_PROJECTION, matProjSave

    ' 現在のバック バッファと z バッファを格納する。
    Dim BackBuffer As Direct3DSurface8, _
        Zbuffer As Direct3DSurface8
    Set BackBuffer = m_D3DDevice.GetRenderTarget()
    Set Zbuffer = m_D3DDevice.GetDepthStencilSurface()

キューブ環境マップの各サーフェスには 90°の視野が含まれることを思い出すこと。アプリケーションで特殊効果などのために視野の角度を変更しない限り、この角度に応じて射影行列を設定するよう注意が必要である。

次のコードは、最も一般的に使用する射影行列を作成および設定する。

    ' 90°の視野を射影に使用する。
    Dim matProj As D3DMATRIX
    D3DXMatrixPerspectiveFovLH matProj, g_pi/4, 1, 1/2, 1000
    m_D3DDevice.SetTransform D3DTS_PROJECTION, matProj

    ' キューブ マップの 6 つのサーフェスに対してループ処理を実行する。
    Dim i As Integer
    For i = 0 To 6

        ' 以下のように、標準ビューをオーバーライドする。
        Dim vEnvEyePt As D3DVECTOR, _
            vLookatPt As D3DVECTOR, _
            vUpVec As D3DVECTOR

        Select Case i

            case D3DCUBEMAP_FACE_POSITIVE_X:
                vLookatPt.x = 1#: vUpVec.y = 1#

            case D3DCUBEMAP_FACE_NEGATIVE_X:
                vLookatPt.x = -1#: vUpVec.y = 1#

            case D3DCUBEMAP_FACE_POSITIVE_Y:
                vLookatPt.y = 1#: vUpVec.z = -1#

            case D3DCUBEMAP_FACE_NEGATIVE_Y:
                vLookatPt.y = -1#: vUpVec.z = 1#

            case D3DCUBEMAP_FACE_POSITIVE_Z:
                vLookatPt.z = 1#: vUpVec.y = 1#

            case D3DCUBEMAP_FACE_NEGATIVE_Z:
                vLookatPt.z = -1#: vUpVec.y = 1#

        End Select

        Dim matView As D3DMATRIX
        D3DXMatrixLookAtLH matView, vEnvEyePt, vLookatPt, vUpVec
        m_D3DDevice.SetTransform D3DTS_VIEW, matView

カメラを正しく配置し、射影行列を設定すると、シーンをレンダリングできる。シーンの各オブジェクトは、通常配置するとおりに配置する。次のコードでは、処理全体がわかるようにするため、このタスクの概略を示す。

        ' レンダリングするキューブ サーフェスを取得する。
        Dim Face As Direct3DSurface8
        Set Face = CubeMap.GetCubeMapSurface i, 0
        m_D3DDevice.SetRenderTarget Face, Zbuffer
        Set Face = Nothing

        m_D3DDevice.BeginScene
        ' ここで、シーンをレンダリングする。
        m_D3DDevice.EndScene

    Next

    ' レンダリング ターゲットをメイン バック バッファに戻す。
    m_D3DDevice.SetRenderTarget BackBuffer, pZBuffer
    Set BackBuffer = Nothing
    Set Zbuffer = Nothing

    ' 元のトランスフォーム行列をリストアする。
    m_D3DDevice.SetTransform D3DTS_VIEW, matViewSave
    m_D3DDevice.SetTransform D3DTS_PROJECTION, matProjSave

End Sub

Direct3DDevice8.SetRenderTarget メソッドの呼び出しには注意すること。キューブ マップ サーフェスにレンダリングするときは、そのサーフェスをカレント レンダリング ターゲット サーフェスとして割り当てる必要がある。深度バッファを使用するアプリケーションでは、そのレンダリング ターゲットに明示的に深度バッファを作成したり、既存の深度バッファをレンダリング ターゲット サーフェスに再割り当てすることができる。上のコードでは、後者の方法を使用している。


キューブ環境マップのテクスチャ座標

キューブ環境マップを指し示すテクスチャ座標は、標準テクスチャを適用する際に使用する単純な u、v スタイルの座標とは異なる。実際、キューブ環境マップではテクスチャ座標を使用しない。テクスチャ座標セットの代わりに、キューブ環境マップでは 3D ベクトルが必要である。適切な頂点フォーマットを指定することが大切である。また、システムにアプリケーションで使用するテクスチャ座標のセット数を知らせるほかにも、各セット内の要素数についての情報を知らせる必要がある。Microsoft® Direct3D® には、3D ベクトルの設定に使用できる CONST_D3DFVFTEXTUREFORMATS 列挙型がある。この列挙のメンバは、論理和演算子を使用して柔軟な頂点フォーマット内で結合できる。

'
' 頂点の柔軟な頂点フォーマット記述子を作成する。
' これには、位置座標、法線、および
' 3D テクスチャ座標セットが 1 つ含まれる。
'
Const D3DFVF CUSTOMVERTEX = (D3DFVF_XYZ Or D3DFVF_NORMAL Or _
                             D3DFVF_TEXCOORDSIZE3_0)
)

ディフューズ ライト マッピングなどの場合には、ベクトルにカメラ空間の頂点法線を使用する。スペキュラ環境マッピングなどの場合には、反射ベクトルを使用するトランスフォーム済み頂点法線については広く理解されているため、ここでは反射ベクトルの計算について詳しく説明する。

独自に反射ベクトルを計算するには、各頂点の位置座標と、ビューポートからその頂点へのベクトルを知っている必要がある。Direct3D ではジオメトリの反射ベクトルを自動的に計算できる。この機能を使用すれば、環境マップのテクスチャ座標を含める必要がないので、メモリを節約できる。さらに、帯域幅が減少し、TnLHAL デバイスの場合は、アプリケーションで独自に計算するよりもはるかに速く計算を実行できる。この機能を利用するには、キューブ環境マップを含むテクスチャ ステージにおいて、D3DTSS_TEXCOORDINDEX テクスチャ ステージ ステートを、D3DTSS_TCI_CAMERASPACEREFLECTIONVECTOR フラグの組み合わせとテクスチャ座標セットのインデックスに設定する。ディフューズ ライト マッピングの場合などには、D3DTSS_TCI_CAMERASPACENORMAL フラグを使用して、システムにカメラ空間のトランスフォーム済み頂点法線をテクスチャのアドレッシング ベクトルとして使用することを知らせることができる。インデックスは、システムがテクスチャのラッピング モードを決定するためにのみ使用する。

次のコードは、この値の使用方法を示している。

'
' 変数 m_D3DDevice は、有効な Direct3DDevice8 オブジェクトである。
'
' ステージ 2 に対してテクスチャ座標を自動生成する。
' ここでは、ステージ 2 にキューブ マップが割り当てられているとする。
' インデックス 1 のテクスチャ座標セットからのラップ モードを使用する。
'
m_D3DDevice.SetTextureStageState 2, D3DTSS_TEXCOORDINDEX, _
                                 (D3DTSS_TCI_CAMERASPACEREFLECTIONVECTOR Or 1)

自動テクスチャ座標生成を有効にすると、2 つの公式のいずれかを使用して各頂点の反射ベクトルが計算される。D3DRS_LOCALVIEWER レンダリング ステートを TRUE に設定すると、次の公式が使用される。

この公式では、R は計算する反射ベクトル、E は位置座標から視点までの正規化されたベクトル、N はカメラ空間の頂点法線である。

D3DRS_LOCALVIEWER レンダリング ステートを FALSE に設定すると、次の公式が使用される。

この公式では、R および N 要素については前の公式と同じである。Nz 要素は頂点法線のワールド空間 z、I は無限大距離にあるビューポートのベクトル (0,0,1) である。システムでは、いずれかの公式で求めた反射ベクトルを使用して、キューブ マップの適切なサーフェスを選択および処理する。

注 ほとんどの場合、アプリケーションでは頂点法線の自動正規化を有効にする必要がある。これを有効にするには、D3DRS_NORMALIZENORMALS を TRUE に設定する。このレンダリング ステートを有効にしていない場合、環境マップの外観が期待とは大きく異なるものになる。


球状環境マッピング

球状環境マッピング (球状マッピングと呼ばれることが多い) は、オブジェクトの周囲の空間の画像またはライティングのエフェクトを、そのオブジェクトの表面に沿って貼り付けていく。このとき、オブジェクトの周囲の空間は、特殊なフォーマットのテクスチャ マップにコード化される。以下のトピックでは、球状マッピングの概念について、および Microsoft Direct3D アプリケーションでの球状マッピングの使用方法について説明する。

  • 球状環境マップとは
  • 球状環境マップのテクスチャ座標
  • 球状環境マップの適用


球状環境マップとは

球状環境マップ、または球状マップは、オブジェクトの周りのシーンの画像またはオブジェクトの周りのライティング エフェクトを含む特殊なテクスチャである。キューブ環境マップとは異なり、球状マップはオブジェクトの周囲の様子を直接表現するわけではない。「環境マッピングとは」のトピックのティーポットの画像は、球状マッピングで実現できる反射エフェクトを示している。

球状マップは、オブジェクトの周囲の 360°の視界を、魚眼レンズで見たように 2D 表現したものである。次の図は、C++ の SphereMap サンプルで使用する球状マップを示している。


球状環境マップのテクスチャ座標

環境マッピングの対象となる各頂点に指定するテクスチャ座標は、テクスチャを湾曲したサーフェスに映るゆがみの関数として処理する必要がある。アプリケーションでは、各頂点のテクスチャ座標を計算して、目的のエフェクトを実現しなければならない。テクスチャ座標を簡単かつ効果的に生成する方法は、頂点法線を入力として使用することである。方法には何種類かあるが、次の公式は、球状マップによる環境マッピングを実行するアプリケーションで共通の公式である。

この公式では、u および v は計算するテクスチャ座標、Nx および Ny はカメラ空間の頂点法線の x および y 要素である。この公式は単純で有効である。法線に正方向の x 要素がある場合、法線は右方向を指しており、u 座標はテクスチャを適切に処理できるように調整される。v 座標も同様、正方向の y は、法線が上方向を指していることを示す。各成分の負の値に対しては、この反対が成り立つ。

法線が直接カメラを指している場合、結果の座標にはゆがみが生じない。両方の座標に +0.5 バイアスを加えると、ゆがみのないポイントは球状マップの中央に配置され、(0, 0, z) の頂点法線によってこのポイントが処理される。この公式では、法線の z 要素は考慮されない。ただし、この公式を使用するアプリケーションでは、正方向の z 要素のある法線を持つ頂点を省略することで計算を最適化できる。このような処理が行われるのは、カメラ空間で法線がカメラから離れる方向 (z の正方向) を指している場合、オブジェクトのレンダリング時に頂点がカリングされるためである。


球状環境マップの適用

環境マップをオブジェクトに適用するときは、その他のテクスチャの場合と同様、Direct3DDevice8.SetTexture メソッドで適切なテクスチャ ステージにテクスチャを設定する。第 1 パラメータには、目的のテクスチャ ステージのインデックスを設定し、第 2 パラメータには、環境マップのキューブ マップ テクスチャの作成時に返された Direct3DCubeTexture8 オブジェクトのアドレスを設定する。必要に応じて色およびアルファ ブレンディング処理と引数を設定して、目的のテクスチャ ブレンディング エフェクトを得ることができる。


フォグ

ここでは、フォグ機能を紹介し、Microsoft® Direct3D® アプリケーションでの各種フォグ機能の使用方法について説明する。説明するトピックは、次のとおりである。

  • フォグの概要
  • フォグ公式
  • フォグ パラメータ
  • フォグ ブレンディング
  • フォグ カラー
  • ピクセル フォグ
  • 頂点フォグ

フォグ ブレンディングは、レンダリング ステートで制御される。プログラム可能なピクセル パイプラインの一部ではない。


フォグの概要

3D シーンにフォグを追加することにより、よりリアルな情景を表現したり、雰囲気を出したり、遠くの景色をぼかすことができる。Microsoft® Direct3D® は、ピクセル フォグと頂点フォグという 2 つのフォグ モデルをサポートする。この 2 つは、それぞれ固有の機能とプログラミング インターフェイスを持つ。

フォグは、基本的には、シーン内のオブジェクトの深度または視点からの距離に基づき、シーン内のオブジェクトの色と選択したフォグ カラーをブレンドして実現する。オブジェクトが遠ざかるに従い、元の色とフォグ カラーのブレンドが増し、シーンに浮かぶ小さい粒子によってオブジェクトの表示がぼけていく。次の画面は、フォグなしでレンダリングしたシーンと、フォグを有効にしてレンダリングした同じシーンを示している。

上の図で、左側のシーンには明瞭な水平線があり、その向こうには実世界では見えるはずの風景が見えない。右側のシーンでは背景色と同一のフォグ カラーを使用して水平線がぼかされ、ポリゴンが遠方では消えるように見える。個別のフォグ エフェクトとクリエイティブなシーン デザインとを組み合わせると、シーン内のオブジェクトの色を和らげ、雰囲気を増すことができる。

Direct3D では、ピクセル フォグと頂点フォグという 2 つの方法でシーンにフォグを追加できる。それぞれの名前は、そのフォグ効果の適用方法を表している。詳細については、「ピクセル フォグ」および「頂点フォグ」を参照すること。簡単に言えば、ピクセル フォグ (テーブル フォグともいう) はデバイス ドライバで実装され、頂点フォグは Direct3D ライティング エンジンで実装される。

注 頂点フォグおよびピクセル フォグのいずれを使用する場合でも、アプリケーションではフォグ エフェクトが正しく適用されるよう適切な射影行列を用意する必要がある。この制約は、Direct3D トランスフォーム & ライティング エンジンを使用しないアプリケーションにも当てはまる。適切な行列の作成方法の詳細については、「W バッファに有効な射影行列」を参照すること。


フォグ公式

Microsoft® Visual Basic® で記述されたアプリケーションでは、Microsoft Direct3D® で距離に応じてフォグ エフェクトの計算を変更することにより、フォグがシーンのオブジェクトの色に与える影響を制御できる。CONST_D3DFOGMODE 列挙には、3 つのフォグ公式を識別するメンバが含まれている。すべての式は、アプリケーションが設定するパラメータを与えられ、距離の関数としてフォグ係数を計算する。距離自体がどのように計算されるかは、範囲ベースのフォグが有効であるかどうかと、射影行列により変化する。詳細については、「視点からの相対深度 対 Z ベースの深度」および「範囲ベースのフォグ」を参照すること。

D3DFOG_LINEAR

この線形公式で、start はフォグ エフェクトが始まる距離、end はフォグ エフェクトがそれ以上増加しなくなる距離、d はシーンの範囲内での深度または視点からの距離を表す。オブジェクトが遠方になるに従って d の値が増加する。線形公式と指数公式は、ピクセル フォグと頂点フォグの両方でサポートされている。

D3DFOG_EXP

D3DFOG_EXP2

上の 2 つの指数公式で、e は自然対数の底 (約 2.71828)、density は 0.0 から 1.0 の範囲の任意のフォグ密度、d はシーンの範囲内での深度、つまり視点からの距離である。

注 システムは、頂点のスペキュラ色のアルファ成分にフォグ係数を格納する。アプリケーションで独自のトランスフォーム & ライティングを実行する場合は、フォグ係数を手動で挿入しておくと、レンダリング時にシステムがそのフォグ係数を適用する。

次の図では、公式のパラメータに共通の値を使用して、これらの公式をグラフに示している。

Direct3D がフォグ エフェクトを計算するときは、上の等式の 1 つのフォグ係数を次に示すブレンディング公式で使用する。

この公式は、現在のポリゴン Ci の色をフォグ係数 f により効果的にスケーリングし、その積を、フォグ係数のビット反転によりスケーリングしたフォグ カラー Cf に加算する。結果として得られるカラー値は、フォグ カラーと元の色のブレンドであり、距離の係数でもある。この公式は、Microsoft DirectX® 7.0 およびそれ以降がサポートするすべてのデバイスに適用される。従来からのランプ デバイスに対しては、フォグ係数はディフューズ色成分とスペキュラ色成分をスケーリングし、0.0 から 1.0 の範囲内 (0.0 と 1.0 を含む) に収める。フォグ係数は、通常、前方クリップ面を 1.0 として始まり、後方クリップ面を 0.0 として減少する。


フォグ パラメータ

フォグ パラメータは、デバイス レンダリング ステートによって制御される。ピクセル フォグおよび頂点フォグではともに、「フォグ公式」で説明するフォグ公式をすべてサポートしている。CONST_D3DFOGMODE 列挙は、Microsoft® Direct3D® で使用するフォグ公式を識別する定数を定義する。D3DRS_FOGTABLEMODE レンダリング ステートは、Direct3D がピクセル フォグに使用するフォグ モードを制御し、D3DRS_FOGVERTEXMODE レンダリング ステートは頂点フォグのモードを制御する。

線形フォグ公式を使用するときは、D3DRS_FOGSTART および D3DRS_FOGEND レンダリング ステートを使用して開始距離およびエンディング距離を設定する。これらの値をシステムがどのように解釈するかは、アプリケーションでピクセル フォグおよび頂点フォグのどちらを使用しているかによって異なる。ピクセル フォグを使用している場合は、z ベースまたは w ベースの深度が使用されるz ベースおよび w ベースの深度の詳細については、「視点からの相対深度 対 Z ベースの深度」を参照すること。フォグの種類およびフォグの開始単位と終了単位を以下の表にまとめる。

フォグの種類 | フォグの開始/終了単位
ピクセル (Z) | デバイス空間 [0.0,1.0]
ピクセル (W) | カメラ空間
頂点 | カメラ空間

D3DRS_FOGDENSITY レンダリング ステートは、指数フォグ公式が有効なときに適用されるフォグ密度を制御する。フォグ密度は、本質的には加重係数であり、指数の距離値を 0.0 から 1.0 (0.0 と 1.0 を含む) にスケーリングする。

システムがフォグ ブレンディングに使用する色は、D3DRS_FOGCOLOR デバイス レンダリング ステートを使用して制御する。D3DColorXRGB 関数を使用して、このレンダリング ステートに有効な値を生成する。詳細については、「フォグ カラー」および「フォグ ブレンディング」を参照すること。


フォグ ブレンディング

フォグ ブレンディングとは、「フォグ公式」で説明するように、シーンに表示する最終色を生成するために、フォグおよびオブジェクトの色にフォグ係数を適用することである。D3DRS_FOGENABLE レンダリング ステートは、フォグ ブレンディングを制御する。次のコードで示すように、このレンダリング ステートを TRUE に設定すると、フォグ ブレンディングが有効になる。デフォルトは FALSE である。

'
' この例では、d3dDevice は Direct3DDevice8 オブジェクトへの
' 有効な参照を格納していると仮定している。
'
On Local Error Resume Next

Call d3dDevice.SetRenderState( _
                     D3DRS_FOGENABLE, _
                     True)

If Err.Number <> D3D_OK Then
    ' エラー処理コード。
End If

フォグ ブレンディングは、ピクセル フォグと頂点フォグの両方に対して有効にしなければならない。これらの種類のフォグの使用方法については、「ピクセル フォグ」および「頂点フォグ」を参照すること。


フォグ カラー

ピクセル フォグおよび頂点フォグの両方のフォグ カラーは、D3DRS_FOGCOLOR レンダリング ステートを使用して設定する。レンダリング ステート値には、D3DColorXRGB 関数が返す RGB 色を指定できる。

次の Microsoft® Visual Basic® サンプル コードは、フォグ カラーを白に設定する。

'
' この例では、変数 d3dDevice は Direct3DDevice8 オブジェクトへの
' 有効な参照であると仮定している。
'
On Local Error Resume Next

Call d3dDevice.SetRenderState( _
                    D3DRS_FOGCOLOR, _
                    D3DColorXRGB(1#, 1#, 1#))

If Err.Number <> D3D_OK Then
    ' エラー処理コード。
End If


ピクセル フォグ

ここでは、ピクセル フォグの概念を紹介し、ピクセル フォグの Microsoft® Direct3D® アプリケーションでの使用方法について説明する。説明するトピックは、次のとおりである。

  • ピクセル フォグについて
  • 視点からの相対深度 対 Z ベースの深度
  • ピクセル フォグの使い方


ピクセル フォグについて

ピクセル フォグという名前は、デバイス ドライバでピクセル単位に計算が実行されることから付けられた名前である。これに対して頂点フォグでは、トランスフォーム & ライティングを実行する際にフォグ エフェクトが計算される。ピクセル フォグは、ドライバによっては、ブレンディング計算に適用するフォグ係数 (各ピクセルの深度を使用) を決定するために事前に計算されたルックアップ テーブルを使用するため、テーブル フォグと呼ばれることもある。

ピクセル フォグは、CONST_D3DFOGMODE 列挙のメンバによって識別されるフォグ公式のいずれかを使用して適用する。ピクセル フォグ公式の実装はドライバ固有であり、ドライバが複雑なフォグ公式をサポートしていない場合は、あまり複雑でない公式を使用すること。

注 「範囲ベースのフォグ」で説明するように、ピクセル フォグは範囲ベースのフォグの計算をサポートしない。


視点からの相対深度 対 Z ベースの深度

深度バッファ内での z 値の不均等なばらつきによって生じる、フォグの不自然なグラフィックス効果を抑えるために、ほとんどのハードウェア デバイスでは、ピクセル フォグに z ベース深度値ではなく視点からの相対深度を使用する。視点からの相対深度とは、本質的には同次座標セットからの w 要素である。Microsoft® Direct3D® は、デバイス空間座標から RHW 要素の逆数を取得して真の w を再生成する。デバイスが視点との相対フォグをサポートしている場合、Direct3DDevice8.GetDeviceCaps メソッドの呼び出し時に D3DCAPS8 型の RasterCaps メンバに D3DPRASTERCAPS_WFOG フラグが設定される。

注 リファレンス ラスタライザを除き、ソフトウェア デバイスは常に z を使用してピクセル フォグ エフェクトを計算する。

視点との相対フォグがサポートされているとき、設定された射影行列でデバイス空間の w 値に対応する、ワールド空間の z 値を生成する場合、システムは z ベース深度よりも視点からの相対深度を優先して自動的に使用する。射影行列を設定するには、Direct3DDevice8.SetTransform メソッドを呼び出し、CONST_D3DTRANSFORMSTATETYPE からの D3DTS_PROJECTION 値を使用し、目的の行列を表す D3DMATRIX 型を渡す。射影行列がこの要件に対応していない場合、フォグ エフェクトは正しく適用されない。適切な行列の生成の詳細については、「W バッファに有効な射影行列」を参照すること。「射影トランスフォームとは」で説明するパースペクティブ射影行列は、適切な射影行列を生成する。

Direct3D では、現在設定されている射影行列を使用して w ベース深度の計算を実行する。したがって、アプリケーションで Direct3D トランスフォーム パイプラインを使用しない場合であっても、目的の w ベース機能を取得するために適切な射影行列を設定しておく必要がある。

Direct3D は射影行列の第 4 列を調べ、要素が [0,0,0,1] (アフィン射影) の場合には、システムは z ベースの深度値をフォグに使用する。この場合、デバイス空間の線形フォグ エフェクトの開始距離および終了距離を指定する必要もある。この範囲は、ユーザーに最も近いポイントを 0.0 とし、最も遠いポイントを 1.0 とした範囲である。


ピクセル フォグの使い方

アプリケーションでピクセル フォグを有効にするには、次の手順を実行する。

Visual Basic アプリケーションでピクセル フォグを有効にするには

  1. D3DRS_FOGENABLE レンダリング ステートを TRUE に設定して、フォグ ブレンディングを有効にする。
  2. D3DRS_FOGCOLOR レンダリング ステートで、目的のフォグ カラーを設定する。
  3. D3DRS_FOGTABLEMODE レンダリング ステートを CONST_D3DFOGMODE 列挙の対応するメンバに設定して、使用するフォグ公式を選択する。
  4. 選択したフォグ モードに必要なフォグ パラメータを、関連するレンダリング ステートに設定する。線形フォグの開始距離と終了距離、指数フォグのフォグ密度も含む。

次のサンプル コードは、これらの手順を示している。

' 簡単にするために、この例では、呼び出しの後で
' エラー値をチェックしない。実際のアプリケーションでは、
' エラー値を正しくチェックすること。
'
' この例では、d3dDevice は Direct3DDevice8 オブジェクトへの
' 有効な参照であると仮定している。
Sub SetupPixelFog(Color As Long, Mode As CONST_D3DFOGMODE)
    Dim StartFog As Single, _
        EndFog As Single, _
        Density As Single

    ' 線形モード用。
    StartFog = 0.5: EndFog = 0.8

    ' 指数モード用。
    Density = 0.66

    ' フォグ ブレンディングを有効にする。
    Call d3dDevice.SetRenderState(D3DRS_FOGENABLE, True)

    ' フォグ カラーを設定する。
    Call d3dDevice.SetRenderState(D3DRS_FOGCOLOR, Color)

    ' フォグ パラメータを設定する。
    If Mode = D3DFOG_LINEAR Then
        Call d3dDevice.SetRenderState(D3DRS_FOGTABLEMODE, Mode)
        Call d3dDevice.SetRenderState(D3DRS_FOGSTART, StartFog)
        Call d3dDevice.SetRenderState(D3DRS_FOGEND, EndFog)
    Else
        Call d3dDevice.SetRenderState(D3DRS_FOGTABLEMODE, Mode)
        Call d3dDevice.SetRenderState(D3DRS_FOGDENSITY, Density)
    End If
End Sub


頂点フォグ

ここでは、頂点フォグを紹介し、頂点フォグの Microsoft® Direct3D® アプリケーションでの使用方法について詳しく説明する。説明するトピックは、次のとおりである。

  • 頂点フォグについて
  • 範囲ベースのフォグ
  • 頂点フォグの使い方


頂点フォグについて

システムは頂点フォグを実行するとき、ポリゴンの各頂点にフォグ計算を適用し、次に、ラスタライズの際、ポリゴンの面に結果を補間する。頂点フォグのエフェクトは、Microsoft® Direct3D® のライティング & トランスフォーム エンジンによって計算される。詳細については、「フォグ パラメータ」を参照すること。

アプリケーションで Direct3D を使用しないでトランスフォーム & ライティングを実行する場合は、アプリケーションで独自にフォグ計算を行う必要がある。この場合、アプリケーションはフォグ係数を計算して、各頂点のスペキュラ色のアルファ成分に置く。公式には、範囲ベースの公式、体積を利用する公式など、どのようなものでも使用できる。Direct3D は与えられたフォグ係数を使用して、各ポリゴンの面を補間する。Direct3D のトランスフォーム & ライティングを使用しないアプリケーションでは、頂点フォグ パラメータを設定する必要はないが、フォグを有効にし、関連するレンダリング ステートによってフォグ カラーを設定しなければならない。詳細については、「フォグ パラメータ」を参照すること。

注 アプリケーションで独自のトランスフォーム & ライティングを実行する場合は、それ独自のフォグ計算を実行する必要がある。したがって、そのようなアプリケーションでは、「フォグ ブレンディング」および「フォグ カラー」で説明するように、フォグ ブレンディングを有効にして、関連するレンダリング ステートによってフォグ カラーを設定するだけでよい。


範囲ベースのフォグ

注 Microsoft® Direct3D® では、Direct3D のトランスフォーム & ライティング エンジンで頂点フォグを使用するときのみ、範囲ベースのフォグの計算を実行する。これは、ピクセル フォグはデバイス ドライバに実装され、現在のところ、ピクセル単位の範囲ベースのフォグをサポートするハードウェアは存在しないためである。アプリケーションで独自のトランスフォーム & ライティングを実行する場合は、範囲ベースの計算かその他の計算による独自のフォグ計算を行う必要がある。

フォグを使用すると、オブジェクトがフォグ カラーと直感的でない方法でブレンドされる不自然なグラフィックス効果が生じることがある。たとえば、2 つのオブジェクトが見えていて、一方はフォグの影響を受けるくらいに遠くにあり、他方は影響されないくらいに近くにあるというシーンを想定する。表示領域が同じ場所で回転した場合、オブジェクトが静止していたとしても、現れるフォグ エフェクトは変化することがある。次の図は、こうした状況を見下ろしたステートを示している。

範囲ベースのフォグは、フォグ エフェクトをより正確に決定する方法である。範囲ベースのフォグでは、Direct3D は視点から頂点までの実際の距離をフォグの計算に使用する。シーンの範囲内での頂点の深度ではなく 2 点間の距離の増加に従ってフォグのエフェクトが増加されるため、不自然な回転効果が回避される。

現在のデバイスが範囲ベースのフォグをサポートしている場合、Direct3DDevice8.GetDeviceCaps メソッドを呼び出すと、デバイスは D3DCAPS8 型の RasterCaps メンバに D3DPRASTERCAPS_FOGRANGE 能力フラグを設定する。範囲ベースのフォグを有効にするには、D3DRS_RANGEFOGENABLE レンダリング ステートを True に設定する。

範囲ベースのフォグは、Direct3D により、トランスフォーム & ライティングの間に計算される。「頂点フォグについて」で説明したように、Direct3D トランスフォーム & ライティング エンジンを使用しないアプリケーションは、独自に頂点フォグの計算も行わなければならない。この場合、範囲ベースのフォグ係数を、各頂点のスペキュラ成分のアルファ成分に設定する。


頂点フォグの使い方

アプリケーションで頂点フォグを有効にするには、次の手順を実行する。

Visual Basic アプリケーションで頂点フォグを有効にするには

  1. D3DRS_FOGENABLE を TRUE に設定して、フォグ ブレンディングを有効にする。
  2. D3DRS_FOGCOLOR レンダリング ステートで、必要なフォグ カラーを設定する。
  3. D3DRS_FOGVERTEXMODE レンダリング ステートを CONST_D3DFOGMODE 列挙のメンバに設定して、目的のフォグ公式を選択する。
  4. 選択したフォグ公式で必要なフォグ パラメータをレンダリング ステートに設定する。

次の Microsoft® Visual Basic® サンプル コードは、これらの手順を示している。

' 簡単にするために、この例では、呼び出しの後で
' エラー値をチェックしない。実際のアプリケーションでは、
' エラー値を正しくチェックすること。
'
' この例では、d3dDevice は Direct3DDevice8 オブジェクトへの
' 有効な参照であると仮定している。
Sub SetupVertexFog(Color As Long, Mode As CONST_D3DFOGMODE, _
                   UseRange As Boolean, Optional Density As Single)

    Dim StartFog As Single, _
        EndFog As Single

    ' 線形フォグの距離を設定する。
    StartFog = 0.5: EndFog = 0.8

    ' フォグ ブレンディングを有効にする。
    Call d3dDevice.SetRenderState(D3DRS_FOGENABLE, True)

    ' フォグ カラーを設定する。
    Call d3dDevice.SetRenderState(D3DRS_FOGCOLOR, Color)

    ' フォグ パラメータを設定する。
    If Mode = D3DFOG_LINEAR Then
        Call d3dDevice.SetRenderState(D3DRS_FOGVERTEXMODE, Mode)
        Call d3dDevice.SetRenderStateSingle(D3DRS_FOGSTART, StartFog)
        Call d3dDevice.SetRenderStateSingle(D3DRS_FOGEND, EndFog)
    Else
        Call d3dDevice.SetRenderState(D3DRS_FOGVERTEXMODE, Mode)
        Call d3dDevice.SetRenderStateSingle(D3DRS_FOGDENSITY, Density)
    End If

    ' 必要に応じて、範囲ベースのフォグを有効にする
    (頂点フォグでのみサポートされる)。' この例では、ドライバが D3DPRASTERCAPS_FOGRANGE 能力を公開する場合にのみ、
    '  UseRange は TRUE に設定
    ' されるとする。
    ' 注  この方が、範囲に基づかないフォグよりも
    '       若干パフォーマンスがよい。
    If UseRange = True Then
        Call d3dDevice.SetRenderState( _
                       D3DRS_RANGEFOGENABLE, True)
    End If
End Sub


ジオメトリ ブレンディング

ここでは、ジオメトリ ブレンディングについて説明する。説明するトピックは、次のとおりである。

  • ジオメトリ ブレンディングについて
  • ブレンディング トランスフォームとレンダリング ステート
  • ブレンディングの重み
  • ジオメトリ ブレンディングの使い方


ジオメトリ ブレンディングについて

Microsoft® Direct3D® では、ジョイント部が滑らかにブレンドされているセグメント化されたポリゴン オブジェクト、特にキャラクタをレンダリングすることで、シーンを一層リアルに表現することができる。これらのエフェクトを一般にスキニングと呼ぶ。このエフェクトは、追加のワールド トランスフォーム行列を頂点の単一セットに適用し、その結果生成される複数のトランスフォーム後の頂点間で線形ブレンドを実行してレンダリング用のジオメトリの単一セットを生成することで実現される。次のバナナのイラストは、この例を示している。

この画像は、ジオメトリ ブレンディングの処理がどのようなものであるかを示している。1 回のレンダリングの呼び出しで、システムはバナナの頂点を取得し、この頂点に対して回転しないトランスフォームと単純な回転のトランスフォームを 1 回ずつ実行して、その結果曲がったバナナを生成する。システムは、ライティングが有効な場合に、頂点法線だけでなく頂点位置座標もブレンドする。アプリケーションは 2 つのブレンディング方法に限定されるわけではない。Direct3D は、最大 4 つのワールド行列 (標準ワールド行列の D3DTS_WORLD など) 間でジオメトリをブレンドできる。

注 ライティングが有効になっている場合、頂点法線が、対応するワールド ビュー行列の逆行列によってトランスフォームされる。この際、重み付けは、頂点位置座標の計算の場合と同様に行われる。D3DRS_NORMALIZENORMALS レンダリング ステートが TRUE に設定されている場合は、結果の法線ベクトルがシステムによって正規化される。

可動結合部のあるモデルの場合、ジオメトリ ブレンディングを使用せずに部分ごとにレンダリングされることが多い。たとえば、人間の腕の 3D モデルを考える。最も単純にして、腕には身体につながる上腕と手につながる下腕がある。2 本の腕はともに肘につながっており、下腕はこの位置座標で回転する。アプリケーションで腕をレンダリングする場合、上腕と下腕の頂点データは保持され、それぞれに個別のワールド トランスフォーム行列が適用される。次のサンプル コードは、これを示している。

Type Arm
    upper_arm_verts(200) As D3DVERTEX
    matWorld_Upper As D3DMATRIX

    lower_arm_verts(200) As D3DVERTEX
    matWorld_Lower As D3DMATRIX
End Type

Dim MyArm As Arm ' これは初期化する必要がある。

腕をレンダリングするには、次のコードで示すように、レンダリングの呼び出しを 2 回実行する。

' 上腕をレンダリングする。
Call d3DDevice.SetTransform(D3DTS_WORLD, MyArm.matWorld_Upper)
Call d3DDevice.DrawPrimitive(D3DPT_TRIANGLELIST, 0, numFaces)

' 下腕をレンダリングして、腕を関節でつなぐワールド行列を更新する。
' 肘で pi/4 ラジアン (45°) ずつ回転するようにする。
MyArm.matWorld_Lower = RotateMyArm(MyArm.matWorld, pi / 4)
Call d3DDevice.SetTransform(D3DTS_WORLD, MyArm.matWorld_Lower)
Call d3DDevice.DrawPrimitive(D3DPT_TRIANGLELIST, 0, numFaces)

次の画像は、このテクニックを使ってバナナを修正したものである。

ブレンドされたジオメトリと、ブレンドされていないジオメトリの違いは明らかである。この例でもその違いははっきりわかる。実際のアプリケーションでは、各モデルをジョイントしても、それほどジョイント部が目立つことはない。しかし、ジョイント部が見苦しく表示されることもある。これは、モデル デザイナにとっては常に課題である。

Direct3D のジオメトリ ブレンディングでは、従来のセグメント モデル シナリオを使用することもできる。しかし、分割されている個々のオブジェクトの表示品質を上げるには、レンダリング時のブレンディング計算が必要となる。これらの追加処理による影響を最小限に抑えるために、Direct3D ジオメトリ パイプラインは、可能な限りオーバーヘッドを発生させないでジオメトリをブレンドできるように最適化される。アプリケーションでは Direct3D のジオメトリ ブレンディング サービスを有効に使用することで、パフォーマンスへの深刻な影響を避けながら、キャラクタをより本物らしく表現することができる。


ブレンディング トランスフォームとレンダリング ステート

Direct3DDevice8.SetTransform メソッドは、ジオメトリがブレンドされる際の行列を識別する CONST_D3DTRANSFORMSTATETYPE 列挙の D3DTS_WORLD、D3DTS_WORLD1、D3DTS_WORLD2、および D3DTS_WORLD3 メンバを認識する D3DTS_WORLD メンバが D3DTS_WORLD0 として認識されることもある。

CONST_D3DRENDERSTATETYPE 列挙には、ジオメトリ ブレンディングを有効にして制御する D3DRS_VERTEXBLEND レンダリング ステートが含まれる。このレンダリング ステートの有効値は、CONST_D3DVERTEXBLENDFLAGS 列挙型によって定義される。ジオメトリ ブレンディンが有効になっている場合、頂点フォーマットにはブレンディングの適切な加重値が含まれていなければならない。

参照

ブレンディング行列の設定、ジオメトリ ブレンディングを有効にする、ブレンディングの重み


ブレンディングの重み

ブレンディングの重み (ベータの重みと呼ぶときもある) は、指定されたワールド行列によって頂点が受ける影響の範囲を制御する。ブレンディングの重みとは、0.0 ～ 1.0 の範囲の浮動小数点値であり、頂点フォーマットでエンコードされる。値が 0.0 の場合、頂点はその行列でブレンドされない。値が 1.0 の場合、頂点は行列の影響をすべて受ける。

ジオメトリ ブレンディングの重みは、頂点フォーマットでエンコードされ、「頂点フォーマットについて」で説明するように、各頂点の位置座標のすぐ後に現れる。Microsoft® Direct3D® レンダリング メソッドに指定する頂点記述に D3DFVF_XYZB1 ～ D3DFVF_XYZB5 の柔軟な頂点フォーマット フラグのいずれかを含めることで、頂点フォーマットにブレンディングの重みを指定する。

重み付けされたブレンド行列間で、システムによって線形ブレンドが実行される。次に、正式なブレンディング公式を示す。

この公式では、vBlend は出力頂点であり、v 要素は適用後のワールド行列によって生成される頂点である。W 要素は、頂点フォーマット内の対応する重みである。n 個の行列間でブレンドされる頂点は、n–1 個のブレンディングの重みを持つことができる (最後のブレンディング行列を除き、各ブレンディング行列に 1 つの重み)。最後のワールド行列の重みは、この公式では Σ で表すように、重みの合計が 1.0 になるようシステムによって自動的に生成される。この公式は、Direct3D がサポートしているケースに合わせて簡略化できる。

これらの公式は、正式なブレンディング公式を、2、3、および 4 つのブレンド行列のケースに合わせて簡略化したものである。

注 Direct3D では、最大 5 つのブレンディングの重みを持つ頂点を定義する柔軟な頂点フォーマット記述子を含めることができるが、このリリースの Microsoft DirectX® では 3 つまでしか使用できない。


ジオメトリ ブレンディングの使い方

ここでは、アプリケーションでのジオメトリ ブレンディングの使用方法について説明する。説明するトピックは、次のとおりである。

  • ブレンディング用の頂点の定義
  • ブレンディング行列の設定
  • ジオメトリ ブレンディングを有効にする


ブレンディング用の頂点の定義

次のユーザー定義型は、2 つの行列間でブレンドする頂点に使用できる。

'
' この頂点の柔軟な頂点フォーマット記述子は次のとおりである。
'
'     FVF = (D3DFVF_XYZB1 Or D3DFVF_NORMAL Or D3DFVF_TEX1)
'
Type D3DBLENDVERTEX
    v As D3DVECTOR
    blend As Single
    n As D3DVECTOR
    tu As Single
    tv As Single
End Type

「ブレンディングの重み」で説明するように、ブレンドの重みは柔軟な頂点フォーマット内の位置座標および RHW データの後ろで、かつ頂点法線の前になければならない。

前の頂点フォーマットには、ブレンディングの重みが 1 つしかないことに注意する。これは、D3DTS_WORLD および D3DTS_WORLD1 トランスフォーム ステートで定義される 2 つのワールド行列があるためである。これら 2 つの行列間でそれぞれの頂点が、1 つの重みを使用してブレンドされる。行列が 3 つある場合、重みは 2 つ必要である。

注 スキンの重みは簡単に定義できる。ジョイントするオブジェクト間の距離の線形関数を使用するとよいが、より滑らかな S 字関数を使用するとさらによい。スキンの重み分布関数を選択すると、必要に応じてジョイント部に鮮明なしわを付けることができる (短い距離間でスキンの重みの変化を大きくする)。

参照

頂点フォーマットについて、柔軟な頂点フォーマット フラグ


ブレンディング行列の設定

Direct3DDevice8.SetTransform メソッドを呼び出して、システムがブレンドする際のトランスフォーム行列を設定する。第 1 パラメータに CONST_D3DTRANSFORMSTATETYPE 列挙から D3DTS_WORLD メンバを設定し、第 2 パラメータには設定する行列のアドレスを設定する。

次の Microsoft® Visual Basic® サンプル コードは、2 つのワールド行列を設定する。これらの行列間でジオメトリをブレンドしてジョイントされた腕のイリュージョンを作成する。

' この例では、変数 d3dDevice は
' 初期化された 3D シーン用の Direct3DDevice8 オブジェクトへの有効な参照であると仮定される。
' 変数 dx は DirectX8 オブジェクトへの有効な参照である。
Dim BendAngle As Single
Dim matUpperArm As D3DMATRIX, _
    matLowerArm As D3DMATRIX

BendAngle = 3.1415926 / 4#  // 45°

' 上腕は動かない。単位行列を使用する。
D3DXMatrixIdentity matUpperArm
Call d3dDevice.SetTransform(D3DTS_WORLD, matUpperArm)

' 下腕は x 軸を中心に回転する。これは上腕につなげる。
D3DXMatrixRotationX matLowerArm, -nBendAngle
Call d3dDevice.SetTransform(D3DTS_WORLD1, matLowerArm)

ブレンディング行列を設定しても、システムはその行列を後で使用できるように単にキャッシュするだけで、頂点のブレンドを開始するわけではない。詳細については、「ジオメトリ ブレンディングを有効にする」を参照すること。


ジオメトリ ブレンディングを有効にする

デフォルトでは、ジオメトリ ブレンディングは無効である。ジオメトリ ブレンディングを有効にするには、Direct3DDevice8.SetRenderState メソッドを呼び出して D3DRS_VERTEXBLEND レンダリング ステートを CONST_D3DVERTEXBLENDFLAGS 列挙からの値に設定する。次のコードは、2 つのワールド行列間でブレンドするための、レンダリング ステートの設定を示している。

Call d3dDevice.SetRenderState(D3DRS_VERTEXBLEND, D3DVBF_1WEIGHT)

D3DRS_VERTEXBLEND が D3DVBF_DISABLE 以外の値に設定されている場合は、頂点フォーマットに適切な個数のブレンディングの重みが含まれていると見なされる。適切な頂点フォーマットを作成すること、およびそのフォーマットの正しい記述を Microsoft® Direct3D® レンダリング メソッドに提供することは開発者の責任である。詳細については、「ブレンディング用の頂点の定義」を参照すること。

ジオメトリ ブレンディングが有効になっている場合、DrawPrimitive レンダリング メソッドでレンダリングされるすべてのオブジェクトに対してジオメトリ ブレンディングが実行される。


インデックス付き頂点ブレンディング

ここでは、Microsoft® Direct3D® 固定機能頂点パイプラインのインデックス付き頂点ブレンディングについて説明する。説明するトピックは、次のとおりである。

  • インデックス付き頂点ブレンディングについて
  • インデックス付き頂点ブレンディング トランスフォームとレンダリング ステート
  • インデックス付き頂点ブレンディングの使い方


インデックス付き頂点ブレンディングについて

インデックス付き頂点ブレンディングは、Microsoft® Direct3D® の頂点ブレンディング サポートを拡張して、行列をブレンディングに使用できるようにしたものである。これらの行列は、行列のインデックスを使用して示される。これらのインデックスは、頂点ごとに提供され、最大 256 個の行列のパレットを参照する。各インデックスは 8 ビットで、各頂点には最大 4 つまでのインデックスを持たせることができるため、1 つの頂点につき 4 つの行列をブレンドすることができる。インデックスは、DWORD にパックされる。インデックスは頂点ごとに指定されるので、最大 12 個の行列が単一の三角形に影響を与えることができ、パレット内の任意の行列が 1 つの描画呼び出しの頂点に影響を与えることができる。このアプローチには、次のような長所がある。

  • 単一の三角形に対して、より多くの行列が影響を与えるようにすることができる。
  • より多くのブレンドされた三角形を、同一の描画呼び出しに渡すことができる。
  • 頂点ブレンディングを三角形インデックスとは独立したものにする。このため、プログレッシブ メッシュを頂点ブレンディングと共に動作させることができる。

この方法の弱点は、頂点処理の前にテッセレーションが行われると、曲面サーフェス プリミティブを処理しないことである。

次の図は、頂点が 4 つの行列によって影響を受ける様子を示している。各頂点は最大 4 つまでのインデックスを持つことができるので、頂点ごとに 4 つの行列をブレンドすることができる。次の図では、0、2、5、および 6 とインデックスを付けられた行列を使用する。

次の図は、1 つの三角形が最高 12 の行列によって影響を受ける様子を示している。頂点ごとに指定されるインデックスを使用して、最大 12 個の行列が単一の三角形に影響を与えることができる。

次の公式は、行列が頂点に与える効果についての一般的な場合を決定する。

Vmodel は、入力モデル空間での頂点の位置座標である。Index0..Index3 は、DWORD にパックされた頂点ごとの行列のインデックスである。M[] は、インデックスを付けるワールド行列の配列で、b0..b2 はブレンド ウェイトである。Vworld は、出力ワールド空間での頂点の位置座標である。


インデックス付き頂点ブレンディング トランスフォームとレンダリング ステート

256 ～ 511 の範囲のトランスフォーム ステートは、8 ビットのインデックスを使ってインデックス付けできる最大 256 個の行列を格納するために確保されている。次の関数を使用して、インデックス 0 ～ 255 を対応するトランスフォーム ステートにマッピングする。

Function D3DTS_WORLDMATRIX(index as Long) As Long
    D3DTS_WORLDMATRIX=(index + 256)
End Function

次のサンプル コードは、Direct3DDevice8.SetTransform メソッドを使用してトランスフォーム ステート番号 256 の行列を単位行列に設定する方法を示している。

Dim matBlend1 As D3DMATRIX

Call D3DXMatrixIdentity(matBlend1)
Call m_D3DDevice.SetTransform(D3DTS_WORLDMATRIX(0), matBlend)

インデックス付き頂点ブレンディングの有効と無効を切り替えるには、D3DRS_INDEXVERTEXBLENDENABLE レンダリング ステートを TRUE に設定する。このレンダリング ステートが有効になっている場合は、頂点ごとにパック Long で行列インデックスを渡さなければならない。このレンダリング ステートを無効にし、頂点ブレンディングを有効にすることは、すべての頂点について行列インデックス 0、1、2、3 を指定することに等しい。次のコードは、Direct3DDevice8.SetRenderState メソッドを使用して、インデックス付き頂点ブレンディングを有効にする。

Call m_D3DDevice.SetRenderState(D3DRS_INDEXVERTEXBLENDENABLE, True)

頂点ブレンディングの有効と無効を切り替えるには、D3DRS_VERTEXBLEND レンダリング ステートを D3DVERTEXBLENDFLAGS 列挙型の D3DRS_DISABLE 以外の値に設定する。このレンダリング ステートが D3DRS_DISABLE に設定されていない場合は、各頂点に必要な加重値を渡さなければならない。次のコードは、SetRenderState を使用して、各頂点対して 3 つの重みで頂点ブレンディングを有効にする。

Call m_D3DDevice.SetRenderState(D3DRS_VERTEXBLEND, D3DVBF_3WEIGHTS)


インデックス付き頂点ブレンディングの使い方

ここでは、以下のトピックについて説明する。

  • インデックス付き頂点ブレンディングのサポートの判定
  • Direct3D に対する行列インデックスの受け渡し


インデックス付き頂点ブレンディングのサポートの判定

インデックス付き頂点ブレンディング行列の最大サイズを判定するには、D3DCAPS8 構造体の MaxVertexBlendMatrix メンバを調べる。次のコードは、Direct3DDevice8.GetDeviceCaps メソッドを使用して、このサイズを取得する。

Dim d3dCaps As D3DCAPS8

Call D3DDevice.GetDeviceCaps(d3dCaps)
IndexedMatrixMaxSize = d3dCaps.MaxVertexBlendMatrixIndex

MaxVertexBlendMatrix に設定された値が 0 の場合、デバイスはインデックス付きの行列をサポートしていない。

注 ソフトウェア頂点処理が使われている場合は、法線ブレンディングがあってもなくても、256 個の行列をインデックス付き頂点ブレンディングに使用できる。


Direct3D に対する行列インデックスの受け渡し

ワールド行列インデックスは、従来の頂点シェーダ (FVF) または宣言を使用して Microsoft® Direct3D® に渡すことができる。

次のコードは、従来の頂点シェーダを使用する方法を示している。

Private Type VERTEX
    x As Single
    y As Single
    z As Single
    weight As Single
    matrixIndices As Long
    normal(2) As Single
End Type

Const D3DFVF_CUSTOMVERTEX = (D3DFVF_XYZB2 Or D3DFVF_NORMAL Or _
                             D3DFVF_LASTBETA_UBYTE4)

従来の頂点シェーダを使用する場合、行列インデックスは D3DFVF_XYZBn フラグを使用して頂点位置座標と共に渡される。行列インデックスは DWORD 内のバイトとして渡され、最後の頂点加重の直後に存在しなければならない。頂点加重も D3DFVF_XYZBn を使用して渡される。パック DWORD は、index3、index2、index1、および index0 を保持し、index0 は DWORD の最下位バイトにある。使用されるワールド行列インデックスの数は、D3DRS_VERTEXBLEND によって定義されるブレンディングに使用される行列の数に渡される数値に等しい。

宣言を使用する場合は、D3DVSDE_BLENDINDICES が行列インデックスを取得する入力頂点レジスタを定義する。行列インデックスは、D3DVSDT_PACKEDBYTE として渡す必要がある。

次のコードは、宣言の使用方法を示している。コンポーネントの順序はまったく重要ではない点に注意すること。

Private Type VERTEX
    x As Single
    y As Single
    z As Single
    matrixIndices As Long
    weight As Single
    normal(2) As Single
End Type

Dim decl(5) As Long

decl(0) = D3DVSD_STREAM(0)
decl(1) = D3DVSD_REG(D3DVSDE_POSITION, D3DVSDT_FLOAT3)
decl(2) = D3DVSD_REG(D3DVSDE_BLENDINDICES, D3DVSDT_PACKEDBYTE)
decl(3) = D3DVSD_REG(D3DVSDE_BLENDWEIGHT, D3DVSDT_FLOAT1)
decl(4) = D3DVSD_REG(D3DVSDE_NORMAL, D3DVSDT_FLOAT3)
decl(5) = D3DVSD_END()


ステンシル バッファ技術

アプリケーションでステンシル バッファを使用して、画像のピクセルをマスクする。このマスクは、ピクセルを描画するかどうかを制御する。ステンシル バッファの詳細については、「ステンシル バッファ」を参照すること。

Microsoft® Direct3D® アプリケーションは、ステンシル バッファを使用して広範な特殊効果を生み出すことができる。ここでは、頻繁に使用される以下のエフェクトについて説明する。

  • ディゾルブ、フェード、およびワイプ
  • デカーリング
  • 合成
  • アウトラインとシルエット


ディゾルブ、フェード、およびワイプ

ディゾルブ、ワイプ、およびフェードなどの映画やビデオでよく使われる特殊効果をアプリケーションで利用することが増えている。

ディゾルブでは、フレームが徐々に変わることによってある画像が別の画像にスムーズに移行する。Microsoft® Direct3D® では、マルチ テクスチャ ブレンディングを使用する方法でこのエフェクトを作成できるが、ディゾルブにステンシル バッファを使用するアプリケーションは、ディゾルブの実行中にテクスチャ ブレンディング機能をほかのエフェクトに利用できる。

ディゾルブを実行するとき、アプリケーションは 2 つの異なる画像をレンダリングしなければならない。アプリケーションはステンシル バッファを使用して、レンダリング ターゲット サーフェスに各画像のどのピクセルを描画するのかを制御する。一連のステンシル マスクを定義して、連続するフレームのステンシル バッファにこれらのマスクをコピーできる。別の方法として、最初のフレーム用の基本ステンシル マスクを定義し、このマスクをインクリメントして変更することもできる。

ディゾルブを開始した時点で、アプリケーションは、開始時の画像のピクセルのほとんどがステンシル テストをパスするようにステンシル関数とステンシル マスクを設定する。最後の画像のほとんどのピクセルは、ステンシル テストに失敗することになる。フレームが続くにつれて、最初の画像のピクセルでテストにパスするピクセルが徐々に少なくなるように、ステンシル マスクを更新する。フレームが続くにつれて、最後の画像のピクセルでテストに失敗するピクセルが徐々に少なくなる。このように、任意のディゾルブ パターンを使用してディゾルブを実行できる。

フェード インまたはフェード アウトは、ディゾルブの特殊なケースである。フェード インするときは、ステンシル バッファを使用して、黒色または白色の画像から 3D シーンのレンダリングにディゾルブする。フェード アウトはこれと逆で、3D シーンのレンダリングから始まって、黒色または白色の画像にディゾルブする。フェードには、どのようなパターンでも使用できる。

Direct3D アプリケーションは、ワイプにも同様な技術を使用する。たとえば、左から右へのワイプを実行する場合、最後の画像が最初の画像の上に徐々にスライドするように左から右に移動する。ディゾルブの場合と同様、連続フレームのステンシル バッファにロードする一連のステンシル マスクを定義するか、最初のステンシル マスクを連続的に修正する必要がある。このステンシル マスクは、最初の画像のピクセルの書き込みを無効にし、最後の画像のピクセルの書き込みを有効にするために使用する。

ワイプの順序とは逆の順序で最後の画像のピクセルを読み出さなければならないという点で、ワイプはディゾルブよりも少し複雑である。つまり、ワイプが左から右に移動する場合、アプリケーションは最後の画像のピクセルを右から左に読み出さなければならない。


デカーリング

Microsoft® Direct3D® アプリケーションは、デカーリング技術を使用して、特定のプリミティブ画像のどのピクセルをレンダリング ターゲット サーフェスに描画するかを制御する。アプリケーションは、デカールをプリミティブの画像に適用して、同一平面上のポリゴンが正しくレンダリングされるようにする。

たとえば、タイヤの跡と黄色の線を道路に適用するとき、この跡は直接道路の上に表示しなければならない。しかし、この跡と道路の z 値は同一である。したがって、深度バッファでは、両者をはっきりと区別できない。背後のプリミティブのピクセルが前面のプリミティブ上にレンダリングされたり、その逆のレンダリングが行われる場合がある。この結果、画像はフレームごとに揺れる。このエフェクトをZ ファイティングまたはフリマリングと呼ぶ。

この問題を解決するには、ステンシルを使用して、デカールが表示される背面プリミティブの部分をマスクする。z バッファリングをオフにして、レンダリング ターゲット サーフェスのマスクで覆っている領域に前面プリミティブの画像をレンダリングする。

マルチ テクスチャ ブレンディングを使用してこの問題を解決することもできるが、この方法を使用すると、アプリケーションで生成できるほかの特殊効果の数が制限される。ステンシル バッファを使用してデカールを適用すると、ほかのエフェクトに対するテクスチャ ブレンディング ステージの制限が解放される。


合成

アプリケーションでステンシル バッファを使用して、2D または 3D 画像を 3D シーンに合成できる。ステンシル バッファのマスクを使用して、レンダリング ターゲット サーフェスの領域を遮蔽する。次に、テキストやビットマップなどの格納 2D 情報を遮蔽領域に書き込むことができる。別の方法として、追加 3D プリミティブをレンダリング ターゲット サーフェスのステンシル マスクされた領域にレンダリングできる。この場合、シーン全体をレンダリングすることもできる。

ゲームでは、複数の 3D シーンを合成することが多い。たとえば、運転ゲームでは通常バックミラーを表示する。バックミラーには、運転者の背後の 3D シーンの表示が含まれる。したがって、バックミラーは、本質的には運転者の前方の風景と合成された 第 2 の 3D シーンと言える。


アウトラインとシルエット

ステンシル バッファは、アウトラインやシルエットなどのより抽象的なエフェクトに使用することもできる。

プログラムで、プリミティブと同じ形状であるが少し小さいステンシル マスクをプリミティブの画像に適用すると、画像はプリミティブのアウトラインだけになる。次に画像のステンシル マスクをした領域を均一の色で塗りつぶし、プリミティブが浮き上がって見えるようにすることができる。

レンダリングするプリミティブとステンシル マスクが同じサイズで同じ形状の場合、本来プリミティブが存在する場所に穴ができる。この穴を黒く塗りつぶすと、プリミティブのシルエットを生成できる。


頂点トゥイーニング

ここでは、複数ストリームを使用した頂点トゥイーニングについて説明する。説明するトピックは、次のとおりである。

  • 頂点トゥイーニングについて
  • 頂点トゥイーニングのアルゴリズム
  • 頂点トゥイーニングの使い方


頂点トゥイーニングについて

頂点トゥイーニングは、2 つのユーザー指定の位置座標間または法線ストリームをブレンドするために使用される。頂点トゥイーニングは、宣言によってのみ使用できる。トゥイーニングを有効にするには、D3DRS_VERTEXBLEND を D3DVBF_TWEENING に設定する。加重を使用した頂点ブレンディングと頂点ブレンディング トゥイーニングは、互いに排他的である。

Visual Basic の「Dolphin サンプル」は、頂点トゥイーニングによる、イルカが水中を移動しているように見えるアニメーションである。以下の画像は、2 つの異なる点におけるイルカを示している。右側の画像のイルカの方が、尾の位置が上から下に下がっており、鼻もより下向きになっている点に注意すること。

宮bmc dolphin1.gif}?


頂点トゥイーニングのアルゴリズム

トゥイーニングは、ライティングやクリッピングの前に行われる。最終的な頂点の位置座標 (法線) は、次のように計算される。

POSITION = POSITION1 * (1.0 - TWEENFACTOR) + POSITION2 * TWEENFACTOR。法線の場合も同様である。


頂点トゥイーニングの使い方

説明するトピックは、次のとおりである。

  • 頂点トゥイーニングのサポートの判定
  • 頂点の宣言の設定
  • 固定機能によるトゥイーニング
  • 頂点シェーダによるトゥイーニング


頂点トゥイーニングのサポートの判定

Microsoft® Direct3D® が頂点トゥイーニングをサポートしているかどうかを調べるには、D3DCAPS8 構造体の VertexProcessingCaps メンバの D3DVTXPCAPS_TWEENING フラグを調べる。次のコードは、Direct3DDevice8.GetDeviceCaps メソッドを使用して、トゥイーニングがサポートされているかどうかを判定する。

'
' この例では d3dDevice は
' 有効な Direct3DDevice オブジェクトであると仮定している。
'
Dim d3dCaps As D3DCAPS8

d3dDevice.GetDeviceCaps d3dCaps
If 0 <> (d3dCaps.VertexProcessingCaps & D3DVTXPCAPS_TWEENING) Then
    ' 頂点トゥイーニングはサポートされている。
End If


頂点の宣言の設定

ベクトル トゥイーニングを使用するには、最初に、2 番目の法線または 2 番目の位置座標を使用するカスタム頂点タイプを設定しなければならない。次のコードは、2 番目の法線と 2 番目の位置座標の両方を含む宣言の例を示している。

Private Type TEX_VERTEX
    Position As D3DVECTOR
    Normal As D3DVECTOR
    Position2 As D3DVECTOR
    Normal2 As D3DVECTOR
};

' タイプが TEX_VERTEX の頂点バッファを作成する。

次の手順は、現在の宣言を設定することである。次のサンプル コードは、この設定方法を示している。

Dim decl(5) As Long

decl(0) = D3DVSD_STREAM(0)
decl(1) = D3DVSD_REG( D3DVSDE_POSITION, D3DVSDT_FLOAT3 ) '位置座標 1
decl(2) = D3DVSD_REG( D3DVSDE_NORMAL, D3DVSDT_FLOAT3 )   '法線 1
decl(3) = D3DVSD_REG( D3DVSDE_POSITION2, D3DVSDT_FLOAT3) '位置座標 2
decl(4) = D3DVSD_REG( D3DVSDE_NORMAL2, D3DVSDT_FLOAT3 )  '法線 2
decl(5) = D3DVSD_END()

カスタム頂点タイプと頂点バッファの作成の詳細については、「頂点バッファの作成」を参照すること。

頂点シェーダの宣言の作成の詳細については、「頂点シェーダ宣言」を参照すること。

注 頂点トゥイーニングが有効になっている場合、2 番目の位置座標または 2 番目の法線は現在の宣言の中に存在しなければならない。


固定機能によるトゥイーニング

次のサンプル コードは、頂点タイプと宣言を設定した後で、固定機能による頂点トゥイーニングを実現する方法を示している。

' この例で使用される変数。
Dim handle As Long
Dim TweenFactor As Float

TweenFactor = 0.3

最初の手順は、次のコードに示すように、Direct3DDevice8.CreateVertexShader メソッドを使用して頂点シェーダを作成することである。

Call d3dDevice.CreateVertexShader(decl, ByVal 0, handle, 0)

CreateVertexShader が受け取る第 1 パラメータは、ベクトル シェーダ宣言へのポインタである。この例では、「頂点の宣言の設定」で宣言した宣言が使用されている。第 2 パラメータは、頂点シェーダ関数の配列となる。この例では頂点シェーダ関数は使用しないので、このパラメータには ByVal 0 を設定する。第 3 パラメータは、返される頂点を表す頂点シェーダ ハンドルとなる。第 4 パラメータには、頂点シェーダの使用コントロールを指定する。D3DUSAGE_SOFTWAREPROCESSING フラグを使用して、頂点シェーダがソフトウェア頂点処理を使用する必要があることを指示することができる。この例では、このパラメータをゼロに設定して、頂点処理はハードウェアで行う必要があることを指示している。

次の手順は、次のコードに示すように、Direct3DDevice8.SetVertexShader メソッドを呼び出して、現在の頂点シェーダを設定することである。

Call d3dDevice.SetVertexShader(handle)

SetVertexShader は、頂点シェーダへのハンドルを受け取る。このパラメータの値として、CreateVertexShader から返るハンドルまたは FVF コードを使用できる。この例では、最後の手順で呼び出される CreateVertexShader から返されるハンドルを使用する。

次の手順は、現在のレンダリング ステートを設定して頂点トゥイーニングを有効にし、トゥイーン係数を設定し、ストリーム ソースを設定することである。次のコードでは、Direct3DDevice8.SetRenderState および Direct3DDevice8.SetStreamSource を使用してこの手順を実行している。

Call d3dDevice.SetRenderState(D3DRS_VERTEXBLEND, D3DVBF_TWEENING)
Call d3dDevice.SetRenderState(D3DRS_TWEENFACTOR, TweenFactor)
Call d3dDevice.SetStreamSource(0 ,vb, 12*Len(vb(0))

現在の頂点シェーダに対して複数のストリームを指定した場合は、トゥイーニング エフェクトに使用されるストリームごとに SetStreamSource を呼び出す必要がある。この時点で、頂点トゥイーニングが有効になる。レンダリング関数を呼び出すと、自動的に頂点トゥイーニングが適用される。


頂点シェーダによるトゥイーニング

頂点シェーダによるトゥイーニングを使用するコードは、固定機能によるトゥイーニングのコードとよく似ている。唯一違う点は、次に示すように Direct3DDevice8.CreateVertexShader 呼び出しだけである。

Call d3dDevice.CreateVertexShader(decl, vsFunction, handle, 0)

CreateVertexShader の第 2 パラメータは、頂点シェーダ関数のトークン配列へのポインタである。この関数は、以下の関数のいずれかを呼び出して作成することもできる。

  • D3DX8.AssembleShader
  • D3DX8.AssembleShaderFromFile

次のサンプル コードでは、AppTween.vsh ファイルから頂点シェーダを組み立てる。

Set vsFunction = d3dx.AssembleShaderFromFile( "AppTween.vsh", 0, ErrorLog, vsFunction)

頂点シェーダ関数の作成の詳細については、「頂点シェーダ関数」を参照すること。


カラー ライティング

D3DLIGHT8 型 (diffuse、specular、ambient) の色に関連するメンバは、D3DCOLORVALUE 型である。これらの型で定義する色は、一般には 0 ～ 1 の範囲の RGBA 値であり、0 が黒に相当する。たいていは光色がこの範囲になるようにするが、特殊効果をねらうときには、この範囲外の値を使用することもできる。たとえば、大きな値の色を設定して、シーンを台なしにするほど強い光を作ることができる。また、色を負の値に設定して、暗色光を作ることができる。暗い光は、シーンで劇的な影を強めたりその他のエフェクトに有用である。


DirectX Graphics の高度なトピック

ここでは、Microsoft® Direct3D® および Direct3DX API の高度な使い方について説明する。ここでの内容は、「DirectX Graphics の使い方」の内容より詳しい。

説明するトピックは、次のとおりである。

  • エフェクトとテクニック
  • 高次プリミティブ
  • 行列スタック
  • ピクセル シェーダ
  • ポイント スプライト
  • 頂点シェーダ
  • X ファイル


エフェクトとテクニック

ここでは、C++ でのアプリケーション開発について説明する。


エフェクトとテクニックについて

ここでは、C++ でのアプリケーション開発について説明する。


エフェクト ファイルの構成要素

ここでは、C++ でのアプリケーション開発について説明する。


エフェクトとテクニックの使い方

ここでは、C++ でのアプリケーション開発について説明する。


エフェクトの作成

ここでは、C++ でのアプリケーション開発について説明する。


テクニックの妥当性確認

ここでは、C++ でのアプリケーション開発について説明する。


テクニックを使用したレンダリング

ここでは、C++ でのアプリケーション開発について説明する。


エフェクトとテクニックの記述の読み出し

ここでは、C++ でのアプリケーション開発について説明する。


エフェクト ファイルのサンプル

ここでは、C++ でのアプリケーション開発について説明する。


高次プリミティブ

ここでは、高次プリミティブについて説明し、アプリケーション内での使用方法を解説する。説明するトピックは、次のとおりである。

  • 高次プリミティブとは
  • レゾリューション増加による品質向上
  • スプラインベースのツールからの直接マッピング
  • 高次プリミティブの使い方


高次プリミティブとは

Microsoft® Direct3D® for Microsoft DirectX® 8.0 では、ポイント、ライン、三角形、およびグリッド プリミティブをサポートしている。これらは、線形補間を超える高次補間をサポートするために拡張された。三角形や線は空間的な広がりがあるにもかかわらず、これまでは線形補間を使ってレンダリングされていた。DirectX 8.0 では、Direct3D が、高次 (最大 5 次までの) 補間を使用するこれらのプリミティブ タイプのレンダリングをサポートしている。また、新しい四辺形プリミティブ タイプがサポートされている。この新しいタイプも高次補間を使ってレンダリングされる。これらの機能は、本来はアニメーションやキャラクタのレンダリングの必要性から追加された。しかし、地形や水面といったサーフェスにも応用できる。

高次プリミティブは、リスト、ストライプ、ファン、またはインデックス化されたメッシュとしてアプリケーション プログラミング インターフェイス (API) に転送されるときに、高次補間をサポートする。これは、頂点自体にエンコードされた追加情報を使って実行される。たとえば、三次補間を有効にするために、法線ベクトルを使って頂点位置の接面を定義することができる。ほとんどの実装では、平面の三角形へのテッセレーションによって高次補間をサポートする。テッセレーションのステップは、論理的に頂点シェーダ ステージの前に適用される。頂点シェーダ API は入力データにセマンティクスを適用しないため、座標位置およびオプションで法線ベクトルを表す頂点ストリーム成分を識別するための特別なメカニズムが用意されている。その他すべての成分はそれ相応に補間される。


分割度増加による品質向上

現在のプリミティブは、滑らかなサーフェスを表現するのに最適なものとは言えない。曲面のレンダリングでは、三次多項式などの高次補間テクニックを使うと、より正確な計算を行うことができる。これにより、シルエットの縁やスペキュラ サーフェス ライティングに現れる不自然な効果を削減または解消し、よりリアルな表現が可能になる。さらに、チップ上でテッセレーションが行われる際、テッセレートされた三角形は、バスの帯域幅に影響を与えない。多くの場合、少量のテッセレーションにより、パフォーマンスにあまり影響を与えることなく、イメージの品質を向上させることができる。

Microsoft® Direct3D® for Microsoft DirectX® 8.0 では、既存のポリゴン指向のツールやアート パイプラインで作成されたコンテンツの分割度を、簡単な方法で向上させることができる。アプリケーションがすべきことは、必要なレベルのテッセレーションを提供することと、法線ベクトルを含む標準的な三角形構文を使ってデータを転送することだけである。


スプラインベースのツールからの直接マッピング

現在、多くのオーサリング ツールが高次プリミティブをサポートしており、通常の平面三角形メッシュよりも強力なモデリング処理を実現している。このようなツールは、妥当な数のパッチが生成されるような効率的な使い方をすれば、アプリケーション プログラミング インターフェイス (API) で直接レンダリングできるようなコンテンツを作成できる。この要件を満たすため、入ってくる頂点データ ストリームを制御ポイントの 2D 配列として解釈し、必要な解像度にテッセレートする、新しいエントリ ポイントが追加された。


高次プリミティブの使い方

ここでは、アプリケーションで高次プリミティブを使用する方法について説明する。

  • 高次プリミティブ サポートの確認
  • パッチの描画


高次プリミティブ サポートの確認

D3DCAPS8 の DevCaps メンバには CONST_D3DDEVCAPSFLAGS 列挙からの値が含まれており、これを照会して、高次プリミティブに関する処理のサポート レベルを確認することができる。次の表は、Microsoft® DirectX® 8.0での高次プリミティブに関連するデバイス機能を示している。

デバイス機能 | 説明
D3DDEVCAPS_NPATCHES | デバイスは、N パッチをサポートしている。
D3DDEVCAPS_QUINTICRTPATCHES | デバイスは、5 次ベジェおよび B スプラインをサポートしている。
D3DDEVCAPS_RTPATCHES | デバイスは、四角形および三角形 (RT) パッチをサポートしている。
D3DDEVCAPS_RTPATCHHANDLEZERO | RT パッチは、ハンドル ゼロを使うと効率的に描画できる。

D3DDEVCAPS_RTPATCHHANDLEZERO はハンドル 0 のパッチが描画できることを意味するのではないことに注意すること。ハンドル ゼロのパッチは、このデバイス機能が設定されていてもいなくても描画される。この能力が設定されている場合は、ハードウェア アーキテクチャはいかなる情報のキャッシングも必要とせず、キャッシュされないパッチ (ハンドル ゼロ) も、キャッシュされたパッチと同様に効率的に描画される。


パッチの描画

次のメソッドを使って、Microsoft® Direct3D® for Microsoft DirectX® 8.0 でパッチを描画できる。

  • Direct3DDevice8.DrawRectPatch
  • Direct3DDevice8.DrawTriPatch

DrawRectPatch は、現在設定されているストリームを使って、Surface パラメータで指定された四角形高次パッチを描画する。Handle パラメータは、パッチとハンドルを関連付けるために使用される。このため、次にパッチが描画される際は、Surface を指定し直す必要がない。これにより、順方向差異係数またはその他の情報を事前に計算してキャッシュすることができ、その結果、同じハンドルを使ったその後の DrawRectPatch への呼び出しが効率的に実行される。

静的パッチについては、アプリケーションが頂点シェーダと適切なストリームを設定し、Surface パラメータ内にパッチ情報を提供し、ハンドルを指定することで、Direct3D が情報をキャプチャしキャッシュできるようにされている。アプリケーションはその後 Surface が ByVal 0 に設定された状態で DrawRectPatch を呼び出すことにより、パッチを効率的に描画できる。キャッシュされたパッチを描画するときは、現在設定されているストリームは無視される。ただし、NumSegments に新しい値を指定して、キャッシュされた NumSegments を上書きできる。また、キャッシュされたパッチをレンダリングする場合は、そのパッチがキャッシュされたときと同じ頂点シェーダを設定する必要がある。

動的パッチについては、パッチのレンダリングごとにパッチ データが変化するため、情報をキャッシュすることは効率的ではない。アプリケーションは、Handle を 0 に設定することで、この情報を Direct3D に伝えることができる。この場合、Direct3D は、現在設定されているストリームおよび NumSegments 値を使ってパッチを描画し、情報のキャッシュを行わない。Handle を 0 に設定した状態で Surface を ByVal 0 に設定すると無効になる。

同じハンドルに Surface を指定し直すことで、アプリケーションは前回キャッシュした情報を上書きすることができる。

NumSegments が ByVal 0 に設定されている場合は、テッセレータは D3DRS_PATCHSEGMENTS を使ってテッセレーションの量を制御する。この場合は、当然、すべての辺に同じテッセレーションが使用される。N パッチには特別なメソッドはない。テッセレーションは、D3DRS_PATCHSEGMENTS によって制御される。法線を指定する必要がある。

DrawTriPatch は DrawRectPatch に似ているが、三角形高次パッチを描画する点が異なる。


行列スタック

ここでは、C および C++ でのアプリケーション開発について説明する。


行列スタックとは

ここでは、C および C++ でのアプリケーション開発について説明する。


シーンの階層の実装

ここでは、C および C++ でのアプリケーション開発について説明する。


ピクセル シェーダ

ここでは、Microsoft® DirectX® 8.0 でサポートされるピクセル処理の最新機能であるピクセル シェーダについて解説し、Microsoft Direct3D® アプリケーションでの使用方法を説明する。説明するトピックは、次のとおりである

  • ピクセル シェーダとは
  • ピクセル シェーダの基本
  • ピクセル シェーダの適用範囲
  • ピクセル シェーダのデータ フロー
  • ピクセル シェーダの使い方
  • ピクセル シェーダの例

このドキュメントで使用されるすべてのピクセル シェーダ コードおよび構文は、Direct3DX ピクセル シェーダ アセンブラに基づくもので、互換性がある。このセクションを読む前に、「ピクセル シェーダ アセンブラ リファレンス」を読み、ピクセル シェーダ アセンブラについての知識を取得しておく必要がある。


ピクセル シェーダとは

次の例は、ピクセル シェーダの簡単な使用方法と、Direct3DX ピクセル シェーダ アセンブラが解釈可能な構文を示している。

ps.1.0          // DirectX8 バージョン。
tex t0          // テクスチャを宣言する。
tex t1          // ライト マップを宣言する。

mov r0, t0
mul r0, r0, t1  // ライト マップを乗算する。
mul r0, r0, v0  // ディフューズを乗算する。
add r0, r0, v1  // スペキュラを追加する。

このピクセル シェーダは、ライト マップ、ディフューズ色、およびスペキュラの追加と共にベース テクスチャを宣言している。

ピクセル シェーダは、色およびアルファ ブレンディング処理およびテクスチャ アドレッシング処理を制御する。Microsoft® Direct3D® for Microsoft DirectX® 8.0 は、ピクセル処理およびテクスチャ ブレンディング処理を定義するためのプロシージャル パラダイムを定義する。このモデルには、仮想マシン アーキテクチャの定義、およびその動作を定義する一連の命令と修飾子が含まれる。このパラダイムは、プロセッサベースの実装である必要はない。

ピクセル シェーダは、次の方法で、DirectX 6.0 および 7.0 のマルチテクスチャ機能を拡張および標準化する。

  • 一般的な読み書きレジスタのセットが追加されたため、D3DTA_CURRENT だけを使用するシリアル カスケードによるサポートよりも柔軟な式を使用できる。これにより、個別の結果レジスタ引数の指定が各ステージで必要となる。
  • D3DTOP_MODULATE2X および D3DTOP_MODULATE4X テクスチャ処理が、どの命令に対しても適用できる個別の修飾子として分割された (両方は不可)。これにより、個別の D3DTOP_MODULATE および D3DTOP_MODULATE2X 処理の必要性がなくなった。
  • バイアス処理修飾子および非バイアス テクスチャ処理修飾子が適用可能になった (両方は不可)。これにより、個別の追加およびバイアス追加処理の必要性がなくなった。
  • 追加を乗算するためにオプションの 3 番目の引数が追加されたため、プロシージャル ピクセル シェーダが arg1 * arg2 + arg0 を実行できるようになっている。これにより、D3DTOP_MODULATEALPHA_ADDCOLOR および D3DTOP_MODULATECOLOR_ADDALPHA テクスチャ処理がなくなった。また、ブレンド処理にもオプションの 3 番目の引数が追加されたため、プロシージャル ピクセル シェーダは arg1 と arg2 の間のブレンド比率として arg0 を使用できるようになった。これにより、D3DTOP_BLENDDIFFUSEALPHA、D3DTOP_BLENDTEXTUREALPHA、D3DTOP_BLENDFACTORALPHA、D3DTOP_BLENDTEXTUREALPHAPM、および D3DTOP_BLENDCURRENTALPHA テクスチャ処理がなくなった。
  • カラー処理およびアルファ処理から、D3DTOP_BUMPENVMAP などのテクスチャ アドレス修正処理が発生し、特にテクスチャ アドレス上で処理を行うための 3 番目の処理タイプとして定義された。

このように拡張された柔軟性をより効率的にサポートするため、アプリケーション プログラミング インターフェイス (API) 構文が DWORD ペアから ASCII アセンブル コード構文に変更された。これにより、プロシージャル ピクセル シェーダによって提供される機能を公開することができる。

注 ピクセル シェーダを使用する場合、スペキュラの追加はレンダリング ステートによって特に制御されなくなり、必要に応じて実装するのはピクセル シェーダの役割となる。しかし、フォグ ブレンディングは固定機能構文によって適用される。

Direct3DX ピクセルシェーダ アセンブラの使用方法についての詳細は、「ピクセル シェーダ アセンブラ リファレンス」を参照すること。


ピクセル シェーダの基本

ここでは、ピクセル シェーダを使用するにあたって必要な基本的情報について説明する。

  • ピクセル シェーダの演算論理単位
  • ピクセル シェーダの命令のペア
  • ピクセル シェーダの処理順序
  • ピクセル シェーダのテクスチャ宣言
  • ピクセル シェーダのテクスチャ アドレッシング
  • ピクセル シェーダのライティング


ピクセル シェーダの演算論理単位

次の図は、ピクセル シェーダの演算論理単位 (ALU) を示している。


ピクセル シェーダの命令のペア

ピクセル シェーダを実行するプロセッサは、2 つのパラレル パイプラインを持っている。1 つはベクトル処理 (RGB) 用で、もう 1 つはスカラー処理 (アルファ) 用である。これらのパイプラインをパラレルで使用することにより、必要なクロック サイクルの合計数が削減され、プロセッサの利用効率とパフォーマンスが非常に向上する。これは、基本的にはピクセルの塗りつぶし速度に影響する。

出力マスクによって 2 つのパイプラインの割り当て方法に影響を与えることはできるが、明示的にペア設定の構文が使用されない限り、処理順序は不明確になる。次の表は、出力マスクおよび関連付けられたパイプを示している。

出力マスク | パイプ
.a | 処理はスカラー パイプにある。
.rgb | 処理はベクトル パイプにある。
.rgba | 処理はスカラー パイプとベクトル パイプの両方にある。これは既にペアと見なされている。

ペアの 2 番目の命令の先頭には + 記号が付けられている。

  mul r0.rgb, t0, v0    // 色成分は乗算。
+ add r0.a,   t0, v0    // ただし、アルファ成分は加算。

内積の命令は特別なケースである。これらはベクトル処理であり、常にベクトル パイプライン内で実行される。このため、スカラー パイプ内で異なる命令を指定しても、次のピクセル シェーダ コード例のようにペアにすることができる。

dp3 r0.rgb, t0, v0
mul r0.a,   t0, v0

ベクトル命令としての内積処理なしに、内積処理をスカラー命令として指定することはできない。


ピクセル シェーダの処理順序

ピクセルの命令と修飾子の処理順序は次のようになる。1) 入力または引数修飾子が適用される。2) 中心となる命令が実行される。3) 出力または命令修飾子が適用される。4) 出力書き込みマスクについて結果が書き込まれる。

入力または引数修飾子については、次のような順序になる。1) バイアスが適用される。2) スケーリングが適用される。3) 正負の反転または補足ステップが実行される。アルファ複製もこのステージで実行される。出力または命令修飾子の場合は、スケール/シフト演算子は彩度ステップよりも優先される。

最終的な処理順序は、次のようになる。

  1. 引数修飾子が適用される。
  2. 中心となる命令が実行される。
  3. 命令修飾子が適用される。
  4. 出力書き込みマスクが適用される。


ピクセル シェーダのテクスチャ宣言

テクスチャ宣言 (テクスチャ アドレッシング命令) は、カラー ブレンディングやアルファ ブレンディングなどの命令とは区別される、個別のピクセル シェーダ命令セットである。これらの命令は、ピクセル シェーダの先頭になければならず、また事前に定義された値しか使用できない。テクスチャ アドレッシング命令は、処理を実行することができる。たとえば、これらの命令を使って、サンプリング ステージがアドレスとして使用しているテクスチャ座標を修正したり、補正特殊効果を有効にしたりできる。

詳細については、「テクスチャ アドレッシング命令」を参照すること。


ピクセル シェーダのテクスチャ アドレッシング

次の図は、ピクセル シェーダのテクスチャ アドレッシングのメカニズムを示している。

テクスチャ処理と関連して、テクスチャ座標を使用し、4 つの入力テクスチャをサンプリングすることで、テクスチャ レジスタ t0、t1、t2、および t3 が結果として得られる。テクスチャ座標とテクスチャ レジスタのマッピングは、D3DTSS_TEXCOORDINDEX テクスチャ ステージ ステートによって制御される。デフォルトでは、すべてのテクスチャ ステージは座標セット 0 からテクスチャ座標を受け取る。命令は以前のテクスチャ レジスタからの結果しか使用できないため、適切な順序で配置する必要がある。

依存テクスチャを使用する場合は、任意のテクスチャを、それより大きい番号のテクスチャの座標補正に使用できる (t1 を使って t2 の座標を補正するなど)。

Direct3DX のピクセル シェーダ アセンブラは、テクスチャ アドレス演算子と修飾子の両方を提供する。詳細については、「ピクセル シェーダ アセンブラ リファレンス」を参照すること。

次のピクセル シェーダ コードは、ライティング ベースのテクスチャ上にバンプ環境マップをプログラミングしたテクスチャ アドレス シェーダを示している。

ps.1.0              // DirectX8 バージョン。
tex t0              // テクスチャを宣言する。
tex t1              // バンプ マップを宣言する。
texbem t3, t1       // 摂動、次に
                    // 環境マップをサンプリングする。
mul r0, v0, t0      // ディフューズを乗算する。
add r0, r0, t3      // バンプ スペキュラ環境マップを追加する。


ピクセル シェーダのライティング

次の図は、ピクセル シェーダのライティングのメカニズムを示している。

たとえば、3D バンプ環境マップの場合、法線マップをサンプリングし、テクスチャ座標を行として使ってポリゴン上に 3 × 3 行列演算を補間する。その後、ディフューズ輝度キューブ マップにトランスフォームおよびインデックスするか、またはスペキュラ環境キューブ マップに反射およびインデックスすることができる。前のパスからベースに適用する。


ピクセル シェーダの適用範囲

ピクセル シェーダは、Microsoft® DirectX® 6.0 および 7.0 のマルチテクスチャ アプリケーション プログラミング インターフェイス (API) で定義されているピクセル ブレンディング機能、特に D3DTSS_COLOROP、D3DTSS_COLORARG1、D3DTSS_COLORARG2、D3DTSS_ALPHAOP、D3DTSS_ALPHAARG1、および D3DTSS_ALPHAARG2 テクスチャ ステージ ステートによって定義される処理、および関連する引数と修飾子に完全に代わるものである。プロシージャル ピクセル シェーダが設定されると、これらのステートは無視される。

ピクセル シェーダの適用範囲についての詳細は、次の各トピックに記述されている。

  • ピクセル シェーダとテクスチャ ステージ ステート
  • ピクセル シェーダとテクスチャ サンプリング
  • シェーダ後のピクセル処理


ピクセル シェーダとテクスチャ ステージ ステート

ピクセル シェーダが処理されているとき、次のテクスチャ ステージ ステートは引き続き保持される。

  • D3DTSS_ADDRESSU
  • D3DTSS_ADDRESSV
  • D3DTSS_ADDRESSW
  • D3DTSS_BUMPENVMAT00
  • D3DTSS_BUMPENVMAT01
  • D3DTSS_BUMPENVMAT10
  • D3DTSS_BUMPENVMAT11
  • D3DTSS_BORDERCOLOR
  • D3DTSS_MAGFILTER
  • D3DTSS_MINFILTER
  • D3DTSS_MIPFILTER
  • D3DTSS_MIPMAPLODBIAS
  • D3DTSS_MAXMIPLEVEL
  • D3DTSS_MAXANISOTROPY
  • D3DTSS_BUMPENVLSCALE
  • D3DTSS_BUMPENVLOFFSET
  • D3DTSS_TEXCOORDINDEX
  • D3DTSS_TEXTURETRANSFORMFLAGS

これらのテクスチャ ステージ ステートはピクセル シェーダの一部ではないため、シェーダのコンパイル時には使用できず、ドライバはそれらについていかなる想定もできない。たとえば、ドライバはその時点では、バイリニア フィルタリングとトライリニア フィルタリングを区別できない。アプリケーションは、現在バインドされているシェーダを再生成しなくても、これらのステートを自由に変更できる。

さらに、使用されるイメージ データを変更するために Direct3DDevice8.SetTexture メソッドを呼び出しても、ピクセル シェーダは無効にならないため、ビット深度に関するテクスチャの形式は自由に変更できる。D3DFMT_A8L8 や D3DFMT_V8U8 といった 2 チャネル テクスチャ フォーマットでの SetTexture の呼び出しも、3 番目のチャネルが 0 に設定されているかのように、引き続き使用できる。


ピクセル シェーダとテクスチャ サンプリング

縮小、拡大、ミップ フィルタリング、およびラップ アドレッシング モードについては、テクスチャ サンプリングおよびフィルタリング処理は標準テクスチャ ステージ ステートによって制御される。詳細については、「テクスチャ ステージ ステート」を参照すること。

この情報はシェーダのコンパイル時にドライバに提供されないため、このステートが変わってもシェーダは処理を続行できる。テクスチャ タイプ (テクスチャ、キューブ テクスチャ、またはボリューム テクスチャ) は、シェーダの構文に明示的に指定する。アプリケーションは、シェーダの実行中に正しいタイプのテクスチャだけを設定しなければならない。シェーダの実行中に間違ったタイプのテクスチャを設定すると、予期しない結果が発生することがある。


シェーダ後のピクセル処理

Microsoft® DirectX® 8.0 では、フォグ ブレンディング、ステンシル処理、レンダリング ターゲット ブレンディングといったピクセル処理は、シェーダの実行後に行う。レンダリング ターゲット ブレンディングの構文は、このトピックで解説するように、新しい機能をサポートするために更新されている。

ピクセル シェーダ入力

DirectX 8.0 では、テクスチャ レジスタに宣言されるすべての色 (ディフューズ色およびスペキュラ色) は、シェーダで使う前に、シェーダへの有効入力の範囲の 0 から 1 の範囲にある (固定されている) と見なされる。位置座標は、ピクセル シェーダの実行前にクリップされていると見なされる。

ピクセル シェーダは、すべての補間値は補間されたパースペクティブ補正であると見なすが、これはすべてのハードウェアで保証されているものではない。アドレス シェーダによってテクスチャ座標として生成された色は、常にパースペクティブ補正の方法で補間される。しかし、これらは補間の間に 0 ～ 1 の範囲に固定される。

ピクセル シェーダ出力

ピクセル シェーダによって出力される結果は、レジスタ r0 のコンテンツである。シェーダの処理が終了した時点でこのレジスタに格納されているデータは、常にフォグ ステージおよびレンダリング ターゲット ブレンダに送信される。


ピクセル シェーダのデータ フロー

ここでは、ピクセル シェーダの仮想マシンへ転送され、また仮想マシンから転送されるデータ フローについて解説する。以下のトピックは、ピクセル シェーダの開発およびその基礎となる仮想マシンについて詳細に理解することを目的として記述されている。

  • ピクセル シェーダ仮想マシンについて
  • ピクセル データの処理


ピクセル シェーダ仮想マシンについて

次の図は、ピクセル シェーダ仮想マシン内での論理データ フローを示している。

各三角形で補間されたデータは、上の図に示したように仮想マシンに転送される。テクスチャ座標およびカラー値は、各ピクセルごとに補間される。テクスチャ座標のマッピングは、D3DTSS_TEXCOORDINDEX テクスチャ ステージ ステートを設定して制御する。たとえば、頂点シェーダからの oD0 データ出力が三角形上で補間され、個々のピクセルの結果がピクセル シェーダの v0 レジスタに設定されるなどである。


ピクセル データの処理

ピクセル データが仮想マシンによってどのように処理されるかを理解するため、オレンジの球体を想像し、それをバンプ マップして、ライトがサーフェスを照らすような環境の中に置くとする。この単純なシナリオで、オレンジの色が、球体を形成する三角形を使って補間されるとする。オレンジの色は、頂点シェーダの oD0 チャネルに渡されたデータから補間されるため、各ピクセルは v0 レジスタを使ってピクセル シェーダに提示される。

次のトピックでは、バンプ マップおよび環境マップのデータを使って、オレンジの球体の最終イメージをレンダリングするために必要なステップを解説する。

  • ピクセル シェーダ仮想マシン用のデータを準備する
  • ピクセル シェーダ仮想マシンを使ってデータを送信する
  • ピクセル シェーダ パイプラインの処理順序

ここでは、特定の例を使ってピクセル シェーダ仮想マシンがデータを処理する方法を示すが、その原則と手順は、各種のピクセル シェーダの開発に応用できる。


ピクセル シェーダ仮想マシン用のデータを準備する

オレンジの球体をバンプ マップと環境マップのデータでレンダリングする前に、バンプ マップおよび環境マップをロードする必要がある。その後各テクスチャ処理ユニットに該当するテクスチャ ステージ ステートを設定する。これには、D3DTSS_BUMPENVMAT00、D3DTSS_BUMPENVMAT01、D3DTSS_BUMPENVMAT10、D3DTSS_BUMPENVMAT11、および D3DTSS_TEXCOORDINDEX テクスチャ ステージ ステートの設定が含まれる。ただし、D3DTSS_COLOROP によって定義されるカラー処理は設定する必要がない。これは、ピクセル単位に実行される処理の定義に、ピクセル シェーダ コードが使用されるためである。一般に、三角形、オブジェクト、またはフレームをレンダリングしている間に一定の状態を維持するテクスチャ ステージ ステートは、ピクセル シェーダ仮想マシンを呼び出す前に設定される。これには、2 × 2 バンプ マッピング行列値が含まれる。ただし、各ピクセルのシェードに使用されるデータは、ピクセル シェーダ言語を使って指定される。

この例では、頂点シェーダ内で発生するフロント エンド処理については触れていない。その代わり、フロント エンドがテクスチャ補間を設定することにより、バンプ データが頂点シェーダの oT0 チャネルを介して渡されると前提する。これは、オレンジの球体の例では、バンプ データへのアクセスに使用されるバンプ マップ アドレスが、ピクセル シェーダの最初のテクスチャ座標レジスタ (t0) に設定されることを意味する。同様に、ライト マップ アドレスは、テクスチャ処理ユニットで変更が行われる前に、頂点シェーダの oT1 チャネルから t1 を介してピクセル シェーダに渡される。


ピクセル シェーダ仮想マシンを使ってデータを送信する

ステージ 0 のテクスチャ処理に使用されるアドレスは、最初のテクスチャ座標レジスタ (t0) を介して提示されるバンプ マップ アドレスとなる。処理は、次のピクセル シェーダ コードに示すように、バンプ データの単純な参照である。

tex t0

ステージ 1 のテクスチャ処理はより複雑である。この場合には、2 × 2 行列がロードされるようにテクスチャ ステージ ステートを設定する必要がある。ここで、視点と光源の間の変更をシミュレートするためにロードできる 2 × 2 行列があることに注目する。これにより、シーン内で視点が移動する際、バンプ マップおよび環境マップを再利用することができる。このため、環境マップへのアドレスは、2 番目のテクスチャ座標である t1 を介して提示されたベース アドレスが、視点調整およびローカル バンプ値によって乗算されたものとなる。より正確には、環境マップへの u 座標は u = t1.r + mat00 * t0.r + mat01 * t0.g であり、環境マップへの v 座標は v = t1.g + mat10 * t0.r + mat11 * t0.g となる。t0.r および t0.g レジスタ成分の値は、実際には du および dv の値であり、ステージ 0 でのバンプ データ参照を表し、レジスタ t0 に格納される。

注 u および v アドレスの計算には、実際のピクセル シェーダ コード内に 2 つのスロットを要する場合がある。これは、ほとんどのハードウェアが、u のロジックを再利用し、その後 v アドレス計算を再利用するためである。現在のハードウェアでは、アドレスをパラレルで計算することはできない。

次の例では、このことをピクセル シェーダ コード内で実行する方法を示している。

ps.1.0         // DirectX8 バージョン。
tex t0         // テクスチャ (バンプ データ) を宣言する。
texbem t1, t0  // 環境マップを宣言し、t0 からデータを取得する。
mov r0, v0     // ディフューズ色のオレンジ色が
               // 各ピクセルのレジスタ v0 を介してピクセル シェーダに
               // 渡されているという仮定に注意すること。
add r0, r0, t1 // スペキュラ環境データを追加する。

これは非常に単純な例であり、多くの場合に適用できるものではない。通常は、バンプ環境マッピングの実行前にベース テクスチャがオブジェクトに適用される。たとえば、テクスチャ データを適用するためのベースとして、白い球体などを送る。これは、サーフェス上のある部分では明るく、ある部分ではやや暗いディフューズ ライトである。この場合、ステージからバンプ環境マッピング処理を外し、ベース テクスチャをディフューズ ライトによって乗算する。次の例では、このことをピクセル シェーダ コード内で実行する方法を示している。

ps.1.0         // DirectX8 バージョン
tex t0         // ベース テクスチャを宣言する。大理石、木材、その他のサーフェス マテリアルなど、
               // 任意のものを宣言できる。
tex t1         // テクスチャ (バンプ データ) を宣言する。
texbem t2, t1  // 環境マップを宣言する。
mul r0, v0, t0 // ディフィーズ ライトでベース テクスチャを乗算する。
add r0, r0, t2 // スペキュラ環境データを追加する。

従来のテクスチャ マッピング (1 ステージ) を使用し、スペキュラを補間し、ピクセル シェーダ仮想マシンのレジスタ v1 を介して利用できるようにすることが推奨される。その他の複雑なピクセル シェーダは、定数レジスタ (c0～c7) に格納されている一連の固定定数を使って構築できる。また、テクスチャ レジスタは多くの場合テクスチャ ステージと共に使用されるが、ピクセル演算論理単位 (ALU) への読み書きである。このためピクセル シェーダは、テクスチャ レジスタをテンポラリ レジスタとして使用できる。また、r0 および r1 は ALU への読み書きであるが、r0 に格納される結果は、深度およびステンシル ロジックに出力できる唯一の結果である。事実、結果をストリームに渡す唯一の方法は、r0 レジスタを使用することである。


ピクセル シェーダ パイプラインの処理順序

ピクセル シェーダ パイプラインのステートは、レンダリング ステートおよびテクスチャ ステージ ステートを設定して、Direct3DDevice8.SetTexture、Direct3DDevice8.SetTextureStageState、Direct3DDevice8.SetPixelShader、および Direct3Ddevice8.SetPixelShaderConstant メソッドを呼び出すことで、その実行時全体にわたって制御できる。これらのステートおよび関数は、ピクセル シェーダの制御フロー、およびピクセル シェーダ パイプラインの各ステップのステートを指定する。次の図は、これらのステップの順序、および各ステップを直接制御する設定を示している。

SetPixelShader に渡されるハンドルの値に応じて、固定機能またはピクセル シェーダ パイプラインのいずれかが 1 つのインスタンスで使用されるが、その両方が使用されることはない。数値によって示される時間になる前に、深度ステンシル テストが行われることがあるが、これによってカラー パイプラインの結果に影響が出ることはない。シェーディング アルゴリズムで処理を進める中、値を固定できる各種パイプライン処理が存在することに注意する。


ピクセル シェーダの使い方

ここでは、アプリケーション内でのピクセル シェーダの使用方法について説明する。

  • ピクセル シェーダ サポートの確認
  • ピクセル シェーダ テクスチャ入力の設定
  • ピクセル シェーダ定数レジスタの設定
  • ピクセル シェーダのコンパイル
  • ピクセル シェーダの作成


ピクセル シェーダ サポートの確認

D3DCAPS8 のメンバを照会して、ピクセル シェーダに関する処理のサポート レベルを確認することができる。次の表は、Microsoft® DirectX® 8.0でのプログラム可能なピクセル処理に関連するデバイス機能を示している。

デバイス機能 | 説明
MaxPixelShaderValue | ピクセル シェーダの算術コンポーネントの最大値。
MaxSimultaneousTextures | サポートされるテクスチャ宣言命令の数。
MaxTextureBlendStages | サポートされる命令の数。
PixelShaderVersion | ピクセル シェーダのサポート レベル。

MaxSimultaneousTextures および MaxTextureBlendStages 能力は、固定機能ピクセル ブレンディング (マルチテクスチャを使用) にのみ適用される。

PixelShaderVersion 機能は、ピクセル シェーダのサポート レベルを示す。Direct3DDevice8.CreatePixelShader メソッドを呼び出したとき、この値以下のバージョン番号を持つピクセル シェーダのみ正常に作成される。主なバージョン番号は、PixelShaderVersion のセカンド バイトにエンコードされる。下位バイトには、マイナー バージョンの番号が含まれる。ピクセル シェーダのバージョンは、各シェーダの最初のトークンによって示される。

ピクセル シェーダ アプリケーションは、MaxSimultaneousTextures および MaxTextureBlendStages デバイス能力をチェックする必要がない。

各実装は、完全にサポートできる最大のピクセル シェーダ バージョンを示す PixelShaderVersion メンバを設定する。このため、PixelShaderVersion によって提示されたバージョン以下のシェーダの作成が失敗することはない。

次の表は、サポートされているピクセル シェーダのバージョン、および関連する機能レベルとレジスタ カウントを示している。

バージョン | 機能 | tn | rn | cn | vn
1.0 | DirectX 8.0 | 4 | 2 | 8 | 2
1.1 | DirectX 8.0 | 4 | 2 | 8 | 2

バージョン 1.0 は、ピクセル シェーダのリファレンスの「命令」に記載されるすべての処理をサポートしている。最大 4 つのテクスチャ アドレス処理、および合計 8 つの命令がサポートされる。このバージョンの場合、テクスチャ レジスタの tn は読み取り専用であり、指定された命令内ではこのテクスチャ レジスタのみ使用できる。

バージョン 1.1 では、最大 4 つのアドレス処理、および 8 つのブレンディング処理をサポートしている。このバージョンの場合、テクスチャ レジスタは読み/書き可能であり、その 2 つを単一の命令内で入力として使用できる。


ピクセル シェーダ テクスチャ入力の設定

入力レジスタ色とテクスチャ ステージの間には、直接マッピングが存在する。Direct3DX ピクセル シェーダ アセンブラのテンポラリ レジスタは、対応するテクスチャ ステージからのテクスチャ カラーと共にプリロードされる。これに対し、テクスチャは、Direct3DDevice8.SetTexture メソッドを呼び出すことによってテンポラリ レジスタに直接バインドされる。

またテクスチャ座標は、直接マップされ、テクスチャ宣言によって定義される。


ピクセル シェーダ定数レジスタの設定

次のメソッドを使って、ピクセル シェーダ定数レジスタに対する値の設定および読み出しを行うことができる。

  • Direct3DDevice8.GetPixelShaderConstant
  • Direct3DDevice8.SetPixelShaderConstant

また、def Direct3DX アセンブラ命令を使って、ピクセル シェーダの定数レジスタを設定することもできる。


ピクセル シェーダのコンパイル

Direct3DX ユーティリティ ライブラリには、ピクセル シェーダをコンパイルするための一連の関数が用意されている。使用できるメソッドは次のとおりである。

  • D3DX8.AssembleShader
  • D3DX8.AssembleShaderFromFile


ピクセル シェーダの作成

Microsoft® DirectX® 8.0 でピクセル シェーダを作成するには、Direct3DDevice8.CreatePixelShader メソッドを使用する。このメソッドには、ブレンディング処理を定義する宣言を渡す。Microsoft Direct3D® は、シェーダのハンドルを返す。シェーダは、CreatePixelShader が呼び出されるときに妥当性が検証される。

DirectX 8.0 ハードウェア モデルの制限により、指定されたシェーダの作成に失敗することもある。


ピクセル シェーダの例

ここでは、ピクセル シェーダ コードに実装されている一般的なエフェクトについて説明する。説明するトピックは、次のとおりである。

  • ディフューズ ライティング
  • スペキュラ マッピング
  • ディフューズ ライティングとスペキュラ マッピング
  • 内積ライティング
  • ピクセル シェーダのサンプル


ディフューズ ライティング

次のシェーダは、ピクセル単位のディフューズ ライティングを実行する。ディフューズ強度を計算するには、dp3 命令を使用する。

ps.1.0                      // DirectX8 バージョン。
tex t0                      // 法線マップを宣言する。
texm3x3pad t1, t0_bx2       // 1 行目トランスフォーム。
texm3x3pad t2, t0_bx2       // 2 行目トランスフォーム。
texm3x3tex t3, t0_bx2       // 3 行目トランスフォーム。
dp3_sat r0, t3_bx2, v0_bx2


スペキュラ マッピング

次のシェーダは、ピクセル単位のスペキュラ マッピングを実行する。

ps.1.0                   // DirectX8 バージョン。
tex t0                   // 法線マップを宣言する。
texm3x3pad   t1, t0      // 1 行目トランスフォーム。
texm3x3pad   t2, t0      // 2 行目トランスフォーム。
texm3x3spec  t3, t0, c0  // 3 行目トランスフォーム。次に空間を反射させ、
                         // キューブ マップをサンプリングする。

mov r0, t3               // フレーム バッファ ブレンダに送る。
                         // これはフレーム バッファの内容に追加される。


ディフューズ ライティングとスペキュラ マッピング

次のシェーダの組み合わせは、ピクセル単位のディフューズ ライティングとスペキュラ マッピングを実行する。

ps.1.0                // DirectX8 バージョン。
tex t0                // 法線マップを宣言する。
texm3x3pad  t1, t0    // 1 行目トランスフォーム。
texm3x3pad  t2, t0    // 2 行目トランスフォーム。
texm3x3spec t3, t0    // 3 行目トランスフォーム。ディフューズ キューブ マップを t2 に、
                      // スペキュラ キューブ マップを t3 にサンプリングする。
mov r0, t3            // スペキュラ色を出力する。


内積ライティング

内積には符号付きデータが必要なため、_bx2 引数修飾子を使って入力データを変換する必要がある。ライティングは、_sat 命令修飾子を使って負の値を固定する。

// ディフィーズはライトの方向である。

ps.1.0      // DirectX8 バージョン。
tex t0      // 法線マップ。
dp3_sat r0, t0_bx2, v0_bx2


ピクセル シェーダのサンプル

ここでは、C++ でのアプリケーション開発について説明する。


ポイント スプライト

ここでは、ポイント スプライトについて説明する。説明するトピックは、次のとおりである。

  • ポイント スプライトとは
  • ポイント プリミティブのレンダリング制御
  • ポイント サイズの計算
  • ポイント レンダリング


ポイント スプライトとは

Microsoft® Direct3D® for Microsoft DirectX® 8.0 では、ポイント スプライトがサポートされているため、ポイント (粒子システム) の高性能レンダリングが可能である。ポイント スプライトとは、任意の形状をテクスチャで定義されたようにレンダリングできるようにする、一般化された汎用ポイントである。

ポイント スプライトは、固定機能ジオメトリ パイプラインではサポートされていない。ポイント スプライトを使用するには、プログラム可能な頂点処理を使う必要がある。


ポイント プリミティブのレンダリング制御

Microsoft® Direct3D® for Microsoft DirectX® 8.0 は、ポイント スプライト (ポイント プリミティブ) のレンダリングを制御するための追加パラメータをサポートしている。これらのパラメータにより、ポイントに可変サイズを設定でき、テクスチャ マップ全体を適用することができる。各ポイントのサイズは、アプリケーションで指定されたサイズと、Direct3D が計算する距離ベースの関数を組み合わせて決定される。アプリケーションは、ポイント サイズを頂点ごとに設定することもでき、また、頂点ごとには設定を行わず、D3DRS_POINTSIZE を設定してポイントに適用することもできる。ポイント サイズはカメラ空間単位で表現される。ただし、アプリケーションがトランスフォーム後の柔軟な頂点フォーマット (FVF) 頂点を渡しているときは、距離ベースの関数は適用されず、ポイント サイズはレンダリング ターゲット上のピクセルの単位で表現される。

ポイントのレンダリング時に計算され使用されるテクスチャ座標は、D3DRS_POINTSPRITEENABLE の設定によって異なる。この値が TRUE に設定されている場合は、各ポイントがテクスチャ全体を表示するようにテクスチャ座標が設定される。これは一般に、ポイントが 1 ピクセルより非常に大きい場合のみに使用する。D3DRS_POINTSPRITEENABLE が FALSE に設定されている場合は、各ポイントの頂点テクスチャ座標がポイント全体に使用される。


ポイント サイズの計算

ポイント サイズは D3DRS_POINTSCALEENABLE によって決定される。この値が FALSE に設定されている場合は、アプリケーションで指定されたサイズがスクリーン空間 (トランスフォーム後) サイズとして使用される。スクリーン空間で Microsoft® Direct3D® に渡される頂点は、ポイント サイズが計算されず、指定されたポイント サイズがスクリーン空間のサイズとして解釈される。

D3DRS_POINTSCALEENABLE が TRUE の場合は、Direct3D が、次の式に従ってスクリーン空間のポイント サイズを計算する。アプリケーションで指定されたポイント サイズは、カメラ空間単位で表現される。

Ss = Vh * Si * sqrt(1/(A + B*De + C*(De2)))

この式の中の入力ポイント サイズ Si は、頂点ごとの値か、または D3DRS_POINTSIZE レンダリング ステートの値である。ポイント スケール係数 D3DRS_POINTSCALE_A、D3DRS_POINTSCALE_B、および D3DRS_POINTSCALE_C は、ポイント A、B、および C によって表される。ビューポート Vh は、ビューポートを表す D3DVIEWPORT8 型の Height メンバである。視点から位置座標への距離 (原点の目) De は、ポイント (Xe, Ye, Ze) の視点空間位置を取り、次の処理を実行することによって計算される。

De = sqrt (Xe2 + Ye2 + Ze2)

最大ポイント サイズ Pmax は、D3DCAPS8 の MaxPointSize メンバまたは D3DRS_POINTSIZE_MAX レンダリング ステートのどちらか小さい方を取って決定される。最小ポイント サイズ Pmin は、D3DRS_POINTSIZE_MIN の値を調べることによって決定される。つまり、最終的なスクリーン空間ポイント サイズ S は次の規則に従って決定される。

  • Ss > Pmax なら S = Pmax
  • Ss < Pmin なら S = Pmin
  • それ以外の場合は S = Ss


ポイント レンダリング

スクリーン空間サイズ S のスクリーン空間ポイント

P = (X, Y, Z, W)

は、次の 4 つの頂点を持つ四辺形としてラスタ化される。

((X+S/2, Y+S/2, Z, W), (X+S/2, Y-S/2, Z, W), (X-S/2, Y-S/2, Z, W), (X-S/2, Y+S/2, Z, W))

頂点カラー属性は頂点それぞれで複製されるため、各ポイントは常にコンスタント カラーでレンダリングされる。

テクスチャ インデックスの割り当ては、D3DRS_POINTSPRITEENABLE レンダリング ステート設定によって制御される。D3DRS_POINTSPRITEENABLE が FALSE に設定されている場合は、頂点テクスチャ座標は頂点それぞれで複製される。D3DRS_POINTSPRITEENABLE が TRUE に設定されている場合は、4 つの頂点のテクスチャ座標は次の値に設定される。

(0.0, 0.0), (0.0, 1.0), (1.0, 0.0), (1.0, 1.0)

これを次の図に示す。

クリッピングが有効にされている場合は、次の規則に従ってポイントがクリッピングされる。シーンがレンダリングされる深度の範囲 (D3DVIEWPORT8 型の MinZ および MaxZ) を頂点が超えている場合、ポイントは視錐台の外に存在し、レンダリングされない。ポイント サイズを考えに入れて、ポイントが完全に x および y のビューポートの外に存在する場合、そのポイントはレンダリングされず、残りのポイントはレンダリングされる。ポイントの位置が x または y のビューポートの外にあっても、部分的に表示できる場合がある。

ポイントは、ユーザー定義クリップ面に正しくクリップされる場合もあり、そうでない場合もある。D3DCAPS8 の PrimitiveMiscCaps メンバ内で D3DPMISCCAPS_CLIPPLANESCALEDPOINTS が設定されていない場合、ポイントは、頂点位置だけに基づき、ポイント サイズは無視して、ユーザー定義クリップ面にクリップされる。このとき、スケーリングされたポイントは、頂点位置がクリップ面の中にある場合は完全にレンダリングされ、頂点位置がクリップ面の外にある場合は破棄される。アプリケーションでは、最大ポイント サイズと同じ大きさの境界ジオメトリをクリップ面に追加することで、不自然な効果の発生を防ぐことができる。

D3DPMISCCAPS_CLIPPLANESCALEDPOINTS ビットが設定されている場合は、スケーリングされたポイントは、ユーザー定義クリップ面に正確にクリップされる。

ハードウェア頂点処理は、ポイント サイズをサポートしている場合もあり、そうでない場合もある。たとえば、D3DCAPS8 型の MaxPointSize メンバが 1.0 または 0.0 に設定されている、HAL デバイス (D3DDEVTYPE_HAL) 上の D3DCREATE_HARDWARE_VERTEXPROCESSING でデバイスを作成すると、すべてのポイントは単一ピクセルになる。1.0 より小さなピクセル ポイント スプライトをレンダリングするには、柔軟な頂点フォーマット (FVF)TL (トランスフォーム済みライティング済み) 頂点、またはソフトウェア頂点処理 (D3DCREATE_SOFTWARE_VERTEXPROCESSING) を使用する必要があり、この場合 Microsoft® Direct3D® ランタイムがポイント スプライト レンダリングをエミュレートする。FVF TL 頂点の詳細については、「トランスフォーム済み ライティング済みの頂点の機能」を参照すること。

頂点処理を実行し (MaxPointSize が1.0f より大きな値に設定された) ポイント スプライトをサポートするハードウェア デバイスは、トランスフォームされないスプライトのサイズ計算に必要であり、また TL 頂点の頂点ごとまたは D3DRS_POINTSIZE の設定を正しく行うためにも必要である。


頂点シェーダ

ここでは、頂点シェーダについて解説し、Microsoft® Direct3D® アプリケーション内での使用方法を説明する。説明するトピックは、次のとおりである

  • 頂点シェーダとは
  • 頂点シェーダの構成要素
  • 頂点シェーダの使い方
  • 頂点シェーダのテクニックとアプリケーション
  • 頂点シェーダの例

このドキュメント内で使用されているすべての頂点シェーダ コードおよび構文は、Direct3DX 頂点シェーダ アセンブラに基いており、互換性がある。このセクションを読む前に、「頂点シェーダ アセンブラ リファレンス」を読み、頂点シェーダ アセンブラについての知識を取得しておく必要がある。


頂点シェーダとは

頂点シェーダは、頂点のロードと処理を制御する。Microsoft® Direct3D® for Microsoft DirectX® 8.0 では、プログラム可能な頂点処理および固定機能頂点処理の 2 種類の頂点処理をサポートしている。DirectX 8.0 のドキュメントでは、「頂点シェーダ」というと主にプログラム可能なモードに適用されるが、頂点シェーダ API 機構では、どちらのタイプも使用できる。頂点シェーダは、作成の際に、プログラム可能な頂点処理を使用するかまたは固定機能頂点処理を使用するか定義される。作成後は、頂点シェーダ自身のハンドルによって参照される。頂点シェーダを編集することはできない。頂点シェーダを変更するには、いったん破棄して作り直す必要がある。

各頂点シェーダには関数が 1 つ含まれており、これによって各頂点に適用する処理が定義される。また宣言も 1 つ含まれており、これによって、入力データ ストリーム内の頂点要素がシェーダによってどのように使用されるかなど、シェーダへの入力が定義される。

頂点シェーダによって実行される頂点処理には、単一の頂点に適用される処理のみが含まれる。頂点処理手順によって得られる出力は、個々の頂点ごとに定義され、それぞれに、クリップ空間位置 (x,y,z,w)、色、テクスチャ座標、フォグ強度、およびポイント サイズ情報が含まれる。これらの位置座標からビューポートへの射影とマッピング、複数の頂点からプリミティブへのアセンブル、およびプリミティブのクリッピングは、後の処理段階によって実行され、頂点シェーダの制御下にはない。

固定機能頂点処理は、トランスフォーム、ライティング、頂点ブレンディング、テクスチャ座標生成を含め、Direct3D for DirectX 7.0 と同じ機能を提供する。プログラム可能な頂点シェーダでは、頂点に適用される処理がシェーダ内で定義されるのに対し、固定機能頂点処理は、ライトやトランスフォームなどを設定する Direct3DDevice8 のメソッドによって設定されたデバイス ステートによって制御される。しかし、機能が固定され共有されている場合でも、宣言は変更できるため、複数の固定機能頂点シェーダを使用することも有用である。これにより、固定機能シェーダに、異なるマルチストリーム入力のレイアウトを提供することができる。

固定機能頂点処理の入力頂点要素のセマンティクスは固定されている。このため、宣言タグによって、入力頂点要素が、座標、法線、色などとして指定される。固定機能頂点シェーダの頂点出力には常に、ピクセル処理のための現在のデバイス ステート設定で必要とされる、座標、ディフューズ色、スペキュラ色、複数のテクスチャ座標が含まれる。

プログラム可能な頂点シェーダには、各頂点に適用される命令の配列によって定義された関数が 1 つ含まれる。入力頂点要素からプログラム可能な頂点シェーダの頂点入力レジスタへのマッピングは、シェーダ宣言で定義されるが、入力頂点要素は、その使用について特定のセマンティクスを持たない。入力頂点要素の解釈は、シェーダの命令に従う。プログラム可能な頂点シェーダの頂点出力は、シェーダ関数内の命令によって明示的に書き込まれる。

Direct3DX 頂点シェーダ アセンブラの詳細については、「頂点シェーダ アセンブラ リファレンス」を参照すること。


頂点シェーダの構成要素

ここでは、頂点シェーダの構成要素について説明する。説明するトピックは、次のとおりである。

  • 頂点シェーダ宣言
  • 頂点シェーダ関数


頂点シェーダ宣言

頂点シェーダの宣言部分では、シェーダの静的な外部インターフェイスを定義している。頂点シェーダ宣言には次の情報が含まれる。

  • 頂点シェーダ入力レジスタに対するストリーム データのバインド。この情報により、各データ ストリーム内の各要素のタイプと頂点入力レジスタ割り当てが定義される。このタイプにより、算術データ型およびディメンション (値 1、2、3、4) が指定される。4 個より少ない値のストリーム データ要素は、0 個、1 個、または複数個の 0.F 値と 1 個の 1.F 値によって 4 個の値に拡張される。
  • 頂点シェーダ入力レジスタから、プリミティブ テッセレータの非明示的データへのバインド。これにより、ストリームからロードされるのでなく、頂点シェーダの前に行われるプリミティブのテッセレーション中に生成される頂点データのロードが制御される。
  • シェーダが現在のシェーダとして設定されるときの定数メモリのデータのロード。各トークンは、1 つまたは複数の連続する 4-DWORD 定数レジスタの値を指定する。これにより、シェーダは、定数メモリの任意のサブセットを更新し、定数メモリの現在の値を格納しているデバイス ステートを上書きすることができる。これらの値は、シェーダが Direct3DDevice8.SetVertexShaderConstant メソッドを介してデバイスにバインドされているときに、DrawPrimitive 呼び出しの間に上書きできる。

宣言配列は、複数のトークンで構成される Long の 1 次元配列である。各トークンは 1 つまたは複数の Long である。1 Long トークン値 0xFFFFFFFF は、宣言配列の末尾を表す特別なトークンである。1 Long トークン値 0x00000000 は、パディング トークンであり、宣言の解析時には無視される。このパディング トークンによって、宣言内でより複雑な編集を実行できる。0x00000000 は、複数語のトークンの最初の Long に続く Long に対して有効な値であることに注意すること。

次のサンプル コードは、宣言の記述方法を示している。この例では、単純な構造体を使って頂点を定義する方法を示す。

Type Vertex
     Position As D3DVECTOR
     Normal As D3DVECTOR
     Diffuse As D3DCOLORVALUE
     TexCoord0 As D3DVECTOR2
End Type

次のサンプル コードは、上記の同じ頂点構造体を宣言子として定義する方法を示している。

Dim Decl(5) As Long
Dim FVF as Long

Decl(0) = D3DVSD_STREAM(0)
Decl(1)= D3DVSD_STREAM( 0 )D3DVSD_REG( D3DVSDE_POSITION,  D3DVSDT_FLOAT3 ),
Decl(2)= D3DVSD_STREAM( 0 )D3DVSD_REG( D3DVSDE_NORMAL,    D3DVSDT_FLOAT3 ),
Decl(3)= D3DVSD_STREAM( 0 )D3DVSD_REG( D3DVSDE_DIFFUSE,   D3DVSDT_D3DCOLOR ),
Decl(4)= D3DVSD_STREAM( 0 )D3DVSD_REG( D3DVSDE_TEXCOORD0, D3DVSDT_FLOAT2 ),
Decl(5)= D3DVSD_STREAM( 0 )D3DVSD_END()

FVF = D3DFVF_POSITION Or D3DFVF_NORMAL Or D3DFVF_DIFFUSE Or _
      D3DFVF_TEX0 Or D3DFVF_TEXCOORDSIZE2(0);

宣言子はデータ ストリームを 0 に設定し、3 つの Long 値で構成される位置座標と法線ベクトルを定義し、4 成分符号なしバイトで構成されるディフューズ成分を定義し、2 つの Long 値で構成されるテクスチャ座標の組を定義する。

固定機能頂点シェーダを使用する際、頂点入力レジスタのマッピングは固定される。これにより、位置座標や法線といった特定の頂点要素は頂点入力メモリ内の特定のレジスタ位置に置かれる必要がある。これらの割り当ては、FVF コードを Direct3DDevice8.SetVertexShader に渡すときに自動的に行われる。明示的なシェーダ宣言を使用する場合は、D3DVSDE プリプロセッサ マクロが、特定の要素のロード先となる頂点入力位置を定義する。宣言トークン配列の生成に使用するマクロの定義については、\Samples\Multimedia\VBSamples\Common\D3DShaders.bas を参照すること。

シェーダ宣言トークン タイプとビット定義については、「頂点シェーダ宣言子関数」を参照すること。

注 固定機能頂点シェーダを使うときは、Direct3DDevice8.SetStreamSource の頂点ストライド セットと頂点サイズが同じサイズでなければならない。宣言を使用する頂点シェーダの場合は、ストリーム ストライドは宣言ストライドより大きくてもかまわない。


頂点シェーダ関数

頂点シェーダの関数部分では、各頂点に適用される処理を定義している。シェーダ関数は、プログラム可能な頂点シェーダにしかない。宣言と同様、シェーダ関数も DWORD の 1 次元配列であり、各頂点に対して実行する命令の順序付きリストを形成している。各命令は複数の DWORD で構成される。

Direct3DX ユーティリティ ライブラリには、ドライバに転送される標準 DWORD トークンを生成するための一連の関数が用意されている。詳細については、「頂点シェーダのコンパイル」を参照すること。


頂点シェーダの使い方

ここでは、アプリケーション内での頂点シェーダの定義方法および使用方法を説明し、頂点シェーダを使って得られるエフェクトについて解説する。

  • 頂点シェーダ サポートの確認
  • 頂点シェーダ定数レジスタの設定
  • 頂点シェーダのコンパイル
  • 頂点シェーダの作成


頂点シェーダ サポートの確認

D3DCAPS8 のメンバを照会して、頂点シェーダに関する処理のサポート レベルを確認することができる。次の表は、Microsoft® DirectX® 8.0 でのプログラム可能な頂点処理に関連するデバイス機能を示している。

デバイス機能 | 説明
MaxPrimitiveCount | DrawPrimitive の各呼び出しの最大プリミティブ数。
MaxVertexIndex | ハードウェア頂点処理に対してサポートされるインデックスの最大サイズ。
MaxStreams | 同時データ ストリームの最大数。
MaxStreamStride | ストライドに対する最大データ ストリーム。
MaxVertexShaderConst | 頂点シェーダの定数レジスタの数。
VertexShaderVersion | 頂点シェーダのサポート レベル。

VertexShaderVersion 機能は、頂点シェーダのサポート レベルを示す。Direct3DDevice8.CreateVertexShader メソッドを呼び出したとき、この値以下のバージョン番号を持つ頂点シェーダのみ正常に作成される。CreateVertexShader に対する頂点シェーダのレベルの指定は、シェーダ トークン ストリームの第 1 トークンで行われる。

次の表は、サポートされている頂点シェーダのバージョンを示している。

バージョン | 機能
0.0 | DirectX 7.0。
1.0 | DirectX 8.0。アドレス レジスタ A0 なし。
1.1 | DirectX 8.0 アドレス レジスタ A0 あり。

サポート レベルの 1.0 と 1.1 の唯一の違いは、A0 レジスタのサポートの有無である。


頂点シェーダ定数レジスタの設定

次のメソッドを使って、頂点シェーダ定数レジスタに対する値の設定および読み出しを行うことができる。

  • Direct3DDevice8.GetVertexShaderConstant
  • Direct3DDevice8.SetVertexShaderConstant

また、def Direct3DX アセンブラ命令を使って、頂点シェーダの定数レジスタを設定することもできる。


頂点シェーダのコンパイル

Direct3DX ユーティリティ ライブラリには、頂点シェーダをコンパイルするための一連の関数が用意されている。使用できるメソッドは次のとおりである。

  • D3DX8.AssembleShader
  • D3DX8.AssembleShaderFromFile


頂点シェーダの作成

頂点シェーダは、シェーダの宣言と機能を指定する 2 つのトークン配列によって定義される。トークン配列は、1 つ以上の DWORD トークンで構成されており、配列の末尾は値 0xFFFFFFFF のトークンで示される。

シェーダの宣言はシェーダの静的な外部インターフェイスを定義しており、頂点レジスタ入力に対するストリーム データのバインドや、シェーダの定数メモリにロードされる値などが含まれる。シェーダ関数は、シェーダの処理を命令の配列として定義する。これらの命令は、シェーダがデバイスにバインドされているときに処理される各頂点に対して、適切な順序で実行される。機能配列を指定しないでシェーダを作成すると、そのシェーダがカレント シェーダのときには、固定機能頂点処理が適用される。

Microsoft® DirectX® 8.0 で頂点シェーダを作成するには、Direct3DDevice8.CreateVertexShader メソッドを使用する。このメソッドには、使用されるパラレル DMA ストリームを定義する宣言、およびブレンディング処理を定義する関数を渡す。Microsoft® Direct3D® は、シェーダのハンドルを返す。シェーダは、CreateVertexShader が呼び出されるときに妥当性が検証される。


頂点シェーダのテクニックとアプリケーション

ここでは、頂点シェーダに実装されている一般的なテクニックについて説明する。説明するトピックは、次のとおりである。

  • 行列パレットのスキニング
  • プロシージャル ジオメトリ
  • 波のモデリング


行列パレットのスキニング

8 ～ 10 の行列で構成されるセットを、パレットとして定数レジスタにロードすることができる。その後、処理された各頂点は、これらの行列のサブセットによってトランスフォームされ、頂点レベルの重み値を使って最終結果にブレンドされる。有用な実装の 1 つとして挙げられるのは、パックされた 4 バイト整数配列を使って、頂点に影響を与えている 4 つの行列の行列パレット アドレスを格納することである。Microsoft® DirectX® 7.0 テクスチャ座標セットなど、標準的な 4D 成分には、これらの行列のブレンドに使用する 4 つの重み値を含むことができる。


プロシージャル ジオメトリ

皮膚の下で筋肉が動くようすは、球体から計算した楕円と、3 つの軸に沿ったスケーリングによってシミュレートできる。これは、入ってくるメッシュ頂点の位置を補正するために評価および使用できる。筋肉の楕円は、相対位置とスケール係数が格納された定数レジスタを更新することによってスケールおよび平行移動できる。


波のモデリング

二次双曲面のような形は、単位矩形内で生成し、入ってくるジオメトリ上に繰り返しマップすることができる。これを実行するには、frc マクロを使って入力頂点 (x, y) 値を単位矩形にマップし、ローカルの双曲面の上昇を計算して、入力頂点 z 値に加算する。これを利用して、海の波などをシミュレートできる。


頂点シェーダの例

ここでは、頂点シェーダ コードに実装されている一般的なエフェクトについて説明する。説明するトピックは、次のとおりである。

  • トランスフォームと定数シェーディング
  • ディレクショナル ライト
  • その他の頂点シェーダのサンプル


トランスフォームと定数シェーディング

次のシェーダは、コンスタント カラーで単一行列のトランスフォームを実行する。入力頂点レジスタ v0 は位置であり、同一と見なされる。トランスフォーム行列は、定数レジスタ (c[0] ～ c[3]) の中にある。ディフューズ色は c[4] にロードされる。

dp4 r0.x, v0, c[0]
dp4 r0.y, v0, c[1]
dp4 r0.z, v0, c[2]
dp4 r0.w, v0, c[3]
mov oD0, c[4]         ; コンスタント カラー
mov oPos, r0          ; 出力

このシェーダは、6 クロック サイクル内に実行される。


ディレクショナル ライト

次のシェーダは、「トランスフォームと定数シェーディング」で示した頂点シェーダの例に、ディレクショナル ライトの光源を追加することで作成できる。

; ディレクショナル光源
dp3 r1.x, v1, c[8]   ; N と L の内積
max r1, r1.x, c[0000]   ; 0 以上にクランプ

; diffuse = dot*diffuse + ambient
mad oD0, r1.x, c[5], c[6]


その他の頂点シェーダのサンプル

SDK のいくつかのサンプルでは、頂点シェーダ ファイルを使用している。拡張子 .vsh が付いたファイルを \Samples\Multimedia\Media ディレクトリで探すこと。


X ファイル

ここでは、Microsoft® DirectX®(.x) ファイルの構造について説明し、アプリケーション内での使用方法を解説する。

説明するトピックは、次のとおりである。

  • X ファイルについて
  • X ファイル インターフェイス階層
  • X ファイル アーキテクチャ
  • X ファイルの使い方


X ファイルについて

.x ファイル フォーマットは、Microsoft® DirectX® 2.0 から採用された。このフォーマットのバイナリ バージョンは、DirectX 3.0 と共にリリースされた。これについてもこのリファレンスで詳しく解説している。その後、DirectX バージョン 6.0 では、DirectX (.x) ファイルに対して読み書きを実行するためのインターフェイスおよびメソッドが採用された。

.x ファイル フォーマットは、詳細な設定が可能な、テンプレート指向のフォーマットであり、メッシュ、テクスチャ、アニメーション、ユーザー定義可能なオブジェクトなどを格納できる。アニメーション セットをサポートしているため、リアルタイムで再生するために事前定義されたパスを格納することができる。インスタンスと階層もサポートされている。インスタンスを使用することで、1 ファイルにつきデータを 1 度しか格納しなくても、メッシュのような、1 つのオブジェクトに対する複数の参照を実行できる。階層は、データ レコードどうしの関係を表現するために使用される。

.x ファイル フォーマットは、下位レベルのデータ プリミティブを提供する。アプリケーションは、テンプレートを使って、この上に高次レベルのプリミティブを定義する。


X ファイル インターフェイス階層

次の図は、.x ファイル クラスどうしの関係を示している。


X ファイル アーキテクチャ

The Microsoft® DirectX® (.x) ファイル フォーマットは、アーキテクチャにもコンテキストにも依存しないテンプレート指向のフォーマットであり、使用方法についての知識は必要ない。また、あらゆるクライアント アプリケーションで使用できる。

次の各トピックで、X ファイル フォーマットの内容と構文について説明する。このファイル フォーマットは、DirectX ソフトウェア開発キット (SDK) で使用する場合は拡張子 .x を使用する。

  • 予約語、ヘッダー、コメント
  • テンプレート
  • データ
  • コンマとセミコロンの使用法


予約語、ヘッダー、コメント

次の表は予約語を示している。予約語を使用することはできない。

  • ARRAY
  • DWORD
  • UCHAR
  • BINARY
  • FLOAT
  • ULONGLONG
  • BINARY_RESOURCE
  • SDWORD
  • UNICODE
  • CHAR
  • STRING
  • WORD
  • CSTRING
  • SWORD
  • DOUBLE
  • TEMPLATE

可変長ヘッダーは必須で、データ ストリームの先頭になければならない。ヘッダーには次のデータが含まれる。

型 | サイズ | 内容 | 意味
マジック番号 (必須) | 4 バイト | "xof" |
バージョン番号 (必須) | 2 バイト | 03 | メジャー バージョン 3
 | 2 バイト | 02 | メジャー バージョン 2
フォーマット タイプ (必須) | 4 バイト | "txt" | テキスト ファイル
 |  | "bin" | バイナリ ファイル
 |  | "tzip" | MSZip 圧縮テキスト ファイル
 |  | "bzip" | MSZip 圧縮バイナリ ファイル
浮動小数点サイズ (必須) | 4 バイト | 0064 | 64 ビット浮動小数点
 |  | 0032 | 32 ビット浮動小数点

次に有効なヘッダーの例を示す。

xof 0302txt 0064

コメントは、テキスト ファイルでのみ使用でき、データ ストリーム内のどこにでも挿入できる。コメントの開始記号は、C++ 形式のダブルスラッシュ (//) か、または番号記号 (#) を使用する。コメントは、複数行にわたることができる。次に有効なコメントの例を示す。

#  This is a comment.
// これもコメントである。


テンプレート

テンプレートは、データ ストリームの解釈方法を定義する。つまり、テンプレートの定義によってデータが乗算される。ここでは、テンプレートのさまざまな側面について説明し、最後にテンプレートの例を紹介する。

  • テンプレートの形式、名前、UUID
  • テンプレートのメンバ
  • テンプレートの限定使用
  • テンプレートの例

テンプレートの中には、ヘッダー テンプレートという特殊なテンプレートが 1 つある。バージョン情報といったアプリケーション固有の情報を定義するために、各アプリケーションにつき 1 つずつのヘッダー テンプレートを定義することが推奨される。このテンプレートが存在する場合、このヘッダーは .x ファイル フォーマット API によって読み込まれる。flags メンバがある場合は、それ以降のデータの解釈方法の決定に使用される。flags メンバが定義されている場合は、DWORD である。現在、ビット 0 の 1 ビットが定義されている。このビットがクリアの場合、ファイル内の以降のデータはバイナリである。設定されている場合は、それ以降のデータはテキストである。複数のヘッダー データ オブジェクトを使って、ファイル内でバイナリとテキストを切り替えることができる。


テンプレートの形式、名前、UUID

テンプレートの形式は次のようになる。

template <template-name> {
<UUID>
<member 1>;
...
<member n>;
[restrictions]
}

テンプレート名には、英数字およびアンダースコア (_) を使用できる。ただし、先頭の文字に数字は使用できない。UUID は、Open Software Foundation の分散コンピューティング環境標準の書式に従うユニバーサル ユニーク識別子であり、山型かっこ (< >) で囲む。例 : <3D82AB43-62DA-11cf-AB39-0020AF71E433>。


テンプレートのメンバ

テンプレート メンバは、名前付きデータ型の後に、オプションの名前、または名前付きデータ型の配列が続くという構成になる。有効なプリミティブ データ型を次の表に示す。

型 | サイズ
WORD | 16 ビット
DWORD | 32 ビット
FLOAT | IEEE 浮動小数点
DOUBLE | 64 ビット
CHAR | 8 ビット
UCHAR | 8 ビット
BYTE | 8 ビット
STRING | NULL 終端文字列
CSTRING | フォーマットされた C 文字列 (サポートされていない)
UNICODE | Unicode™ 文字列 (サポートされていない)

追加のデータ型も、テンプレート内でデータ ストリームの前に定義されていれば、テンプレート定義内で参照できる。前方参照は実行できない。

有効なデータ型はすべてテンプレート定義内で配列として表現できる。基本的な構文の例を次に示す。

array <data-type> <name>[<dimension-size>];

<dimension-size> は、整数か、またはほかのテンプレート メンバへの名前付き参照である。名前付き参照の場合は、参照先の値が代入される。使用できる配列は n 次元である。ここで n とは、定義文の後に付けられた角かっこのペアの数である。次に例を示す。

array DWORD FixedHerd[24];
array DWORD Herd[nCows];
array FLOAT Matrix4x4[4][4];


テンプレートの限定使用

テンプレートは、開くまたは閉じる、あるいは限定使用できる。これにより、テンプレートに定義されたデータ オブジェクトの直接階層で表示されるデータ型を決定できる。開かれたテンプレートには制約はなく、閉じられたテンプレートはすべてのデータ型を拒否する。限定使用テンプレートでは、指定したデータ型を使うことができる。

テンプレートが開かれていることを示す構文は、3 つのピリオドを角かっこで囲んだものである。

[ ... ]

テンプレートが限定使用されることを示す構文は、名前付きデータ型 (オプションで角かっこ内に UUID 付き) をコンマで区切って並べたものである。

[ { data-type [ UUID ] , } ... ]

これらのどちらも指定されていない場合は、テンプレートが閉じていることを示す。


テンプレートの例

次にテンプレートの例を示す。

template Mesh {
<3D82AB44-62DA-11cf-AB39-0020AF71E433>
DWORD nVertices;
array Vector vertices[nVertices];
DWORD nFaces;
array MeshFace faces[nFaces];
 [ ... ]                // 開かれたテンプレート
}
template Vector {
<3D82AB5E-62DA-11cf-AB39-0020AF71E433>
FLOAT x;
FLOAT y;
FLOAT z;
}                        // 閉じられたテンプレート
template FileSystem {
<UUID>
STRING name;
[ Directory <UUID>, File <UUID> ]    // 限定使用されるテンプレート
}


データ

データ オブジェクトには、実際のデータか、またはそのデータへの参照が含まれる。各データ オブジェクトにはそれぞれ、データ型を定義するテンプレートがある。次の各トピックで、データ オブジェクトの形式と構成要素について説明する。

  • 形式、識別子、名前
  • データ メンバ


形式、識別子、名前

データ オブジェクトの形式は次のようになる。

<Identifier> [name] { [<UUID>]
<member 1>;
...
<member n>;
}

識別子は必須で、事前に定義されたデータ型またはプリミティブに一致しなければならない。名前はオプションである。メンバの詳細については、「データ メンバ」を参照すること


データ メンバ

データ メンバとは、データ オブジェクト、データ参照、整数リスト、浮動小数点リスト、または文字列リストのいずれかである。

データ オブジェクトとは、ネストされたデータ オブジェクトである。これにより、ファイル フォーマットの階層構造的性質を表現できる。階層構造の中で使用できるネストされたデータ オブジェクトのタイプは制限することができる。詳細については「テンプレート」を参照すること。

データ参照とは、前に存在するデータ オブジェクトへの参照である。次に例を示す。

{
  name |
  UUID |
  name UUID
}

整数リストとは、セミコロンで区切られた整数のリストである。次に例を示す。

1; 2; 3;

浮動小数点リストとは、セミコロンで区切られた浮動小数点のリストである。次に例を示す。

1.0; 2.0; 3.0;

文字列リストとは、セミコロンで区切られた文字列のリストである。次に例を示す。

"Moose"; "Goats"; "Sheep";


コンマとセミコロンの使用法

ファイル フォーマットの構文で最も複雑なのは、コンマとセミコロンの使用法である。これらの使用法は厳密に規定されている。コンマは、配列のメンバの区切りを表す。セミコロンは、各データ項目の終わりを表す。

たとえば、テンプレートが次のように定義されている場合、

template mytemp {
DWORD myvar;
}

このテンプレートのインスタンスは次のようになる。

mytemp dataTemp {
1;
}

ほかのテンプレートを含むテンプレートが次のように定義されている場合、

template mytemp {
DWORD myvar;
DWORD myvar2;
}
template container {
FLOAT aFloat;
mytemp aTemp;
}

このテンプレートのインスタンスは次のようになる。

container dataContainer {
1.1;
2; 3;;
}

container の中の mytemp を表す 2 行目の終わりには、セミコロンが 2 つ付けられている。最初のセミコロンはコンテナ内のデータ項目 aTemp の終わりを表し、2 番目のセミコロンは container の終わりを表している。

配列が次のように定義されている場合、

Template mytemp {
array DWORD myvar[3];
}

このインスタンスは次のようになる。

mytemp aTemp {
1, 2, 3;
}

配列の例では、コンマで表されているため、データ項目をセミコロンで区切る必要はない。最後にセミコロンが付けられている場合は、配列の終わりを表す。

次のような、テンプレートによって定義されたデータ項目の配列を含むテンプレートの場合、

template mytemp {
DWORD myvar;
DWORD myvar2;
}
template container {
DWORD count;
array mytemp tempArray[count];
}

このインスタンスは次のようになる。

container aContainer {
3;
1;2;,3;4;,5;6;;
}


X ファイルの使い方

ここでは、Microsoft® Direct3D® アプリケーション内での .x ファイルの使用方法について説明する。説明するトピックは、次のとおりである。

  • X ファイルのロード
  • X ファイルへの保存
  • キューブの作成
  • 3D モデルから X ファイルへの変換とエクスポート


X ファイルのロード

x. ファイルをロードするには、次の手順を実行する。

  1. DirectX8.DirectXFileCreate メソッドを使って DirectXFile オブジェクトを作成する。
  2. ロードする Microsoft® DirectX® ファイルにテンプレートがある場合は、DirectXFile.RegisterTemplates メソッドを使ってそれらのテンプレートを登録する。
  3. DirectXFile.CreateEnumObject メソッドを使って DirectXFileEnum 列挙オブジェクトを作成する。
  4. ファイル内のオブジェクトをループする。各オブジェクトに対して、次の手順を実行する。
    1. DirectXFileEnum.GetNextDataObject メソッドを使って各 DirectXFileData オブジェクトを取得する。
    2. DirectXFileData.GetType メソッドを使ってデータの型を取得する。
    3. DirectXFileData.GetData メソッドを使ってデータをロードする。
    4. オブジェクトにオプションのメンバがある場合は、DirectXFileData.GetNextObject メソッドを呼び出してオプションのメンバを取得する。
    5. DirectXFileData オブジェクト変数を Nothing に設定する。
  5. DirectXFileEnum オブジェクト変数を Nothing に設定する。
  6. DirectXFile オブジェクト変数を Nothing に設定する。


X ファイルへの保存

.x ファイル テンプレートとデータを .x ファイルに保存するには、次の手順を実行する。

  1. DirectX8.DirectXFileCreate メソッドを使って DirectXFile オブジェクトを作成する。
  2. DirectXFile.RegisterTemplates メソッドを使って、使用するすべてのテンプレートについて Microsoft® DirectX® ファイル システムに情報を与える。
  3. DirectXFile.CreateSaveObject メソッドを使って DirectXFileSave オブジェクトを作成する。
  4. 必要に応じて、DirectXFileSave.SaveTemplates メソッドを使ってテンプレートを保存する。
  5. 保存するオブジェクトをループする。各最上位レベルのオブジェクトに対して、次の手順を実行する。
    1. DirectXFileSave.CreateDataObject メソッドを使って、ファイル内の最上位オブジェクトとして DirectXFileData オブジェクトを作成する。最上位データ オブジェクトにオプションの子オブジェクトがある場合は、次の手順で定義されている適切なメソッドを使ってオブジェクトに追加する。
    2. テンプレートによって許可されていれば、各 DirectXFileData オブジェクトはオプションの子オブジェクトを持つことができる。子オブジェクトのタイプは、DirectXFileData、DirectXFileReference、または DirectXFileBinary の 3 種類のうちのいずれでも可能である。後の手順で示すような、それぞれのタイプに適した方法で各オプションの子メンバをオブジェクト リストに追加しながら、保存するオブジェクトをループする。オブジェクト タイプが Data の場合は、DirectXFileSave.CreateDataObject メソッドを呼び出して DirectXFileData オブジェクトを作成し、その後 DirectXFileData.AddDataObject メソッドを呼び出して、オブジェクトの子として追加する。オブジェクト タイプが Data Reference の場合は、DirectXFileData.AddDataReference メソッドを呼び出して、オブジェクトの子としてデータ参照オブジェクトを作成および追加する。オブジェクト タイプが Binary の場合は、DirectXFileData.AddBinaryObject メソッドを呼び出して、オブジェクトの子としてバイナリ オブジェクトを作成および追加する。
    3. DirectXFileSave.SaveData メソッドを呼び出して、データ オブジェクトとすべての子を保存する。
    4. DirectXFileData オブジェクトを Nothing に設定する。
  6. DirectXFileSave オブジェクトを Nothing に設定する。
  7. DirectXFile オブジェクトを Nothing に設定する。


キューブの作成

ここでは、単純なキューブについて説明し、テクスチャ、フレーム、およびアニメーションの追加方法について解説する。

  • 単純なキューブの定義
  • テクスチャの追加
  • フレームとアニメーションの追加


単純なキューブの定義

次のファイルは、4 本の赤い辺と 2 本の緑の辺を持つ単純なキューブを定義する。このファイルでは、オプションの情報を使って、Mesh テンプレートで定義されたデータ オブジェクトに情報を追加している。

Material RedMaterial {
1.000000;0.000000;0.000000;1.000000;;    // R = 0.0, G = 1.0, B = 0.0
0.000000;
0.000000;0.000000;0.000000;;
0.000000;0.000000;0.000000;;
}
Material GreenMaterial {
0.000000;1.000000;0.000000;1.000000;;     // R = 0.0, G = 1.0, B = 0.0
0.000000;
0.000000;0.000000;0.000000;;
0.000000;0.000000;0.000000;;
}
// 8 つの頂点と 12 の面 (三角形) を持つメッシュを定義する。
// メッシュ内のオプションのデータ オブジェクトを使って、
// マテリアル、法線、およびテクスチャ座標を指定する。
Mesh CubeMesh {
8;                                // 8 個の頂点。
1.000000;1.000000;-1.000000;,     // 頂点 0。
-1.000000;1.000000;-1.000000;,    // 頂点 1。
-1.000000;1.000000;1.000000;,     // 同様に続く。
1.000000;1.000000;1.000000;,
1.000000;-1.000000;-1.000000;,
-1.000000;-1.000000;-1.000000;,
-1.000000;-1.000000;1.000000;,
1.000000;-1.000000;1.000000;;

12;                      // 12 個の面。
3;0,1,2;,                // 面 0 には 3 個の頂点がある。
3;0,2,3;,                // 同様に続く。
3;0,4,5;,
3;0,5,1;,
3;1,5,6;,
3;1,6,2;,
3;2,6,7;,
3;2,7,3;,
3;3,7,4;,
3;3,4,0;,
3;4,7,6;,
3;4,6,5;;

// すべての必須データが定義された。ここで、ファイル フォーマットの
// 階層構造的性質を使ってオプションのデータを定義する。
MeshMaterialList {
2;                    // 使用されるマテリアルの数。
12;                   // 各面のマテリアル。
0,                    // 面 0 は最初のマテリアルを使用する。
0,
0,
0,
0,
0,
0,
0,
1,                    // 面 8 は 2 番目のマテリアルを使用する。
1,
1,
1;;
{RedMaterial}         // マテリアル 0 および 1 の
{GreenMaterial}       // 定義への参照。
}
MeshNormals {
8;                    // 8 個の法線を定義する。
0.333333;0.666667;-0.666667;,
-0.816497;0.408248;-0.408248;,
-0.333333;0.666667;0.666667;,
0.816497;0.408248;0.408248;,
0.666667;-0.666667;-0.333333;,
-0.408248;-0.408248;-0.816497;,
-0.666667;-0.666667;0.333333;,
0.408248;-0.408248;0.816497;;
12;                   // 12 個の面に対して法線を定義する。
3;0,1,2;,
3;0,2,3;,
3;0,4,5;,
3;0,5,1;,
3;1,5,6;,
3;1,6,2;,
3;2,6,7;,
3;2,7,3;,
3;3,7,4;,
3;3,4,0;,
3;4,7,6;,
3;4,6,5;;
}
MeshTextureCoords {
8;                        // 各頂点に対してテクスチャ座標を定義する。
0.000000;1.000000;
1.000000;1.000000;
0.000000;1.000000;
1.000000;1.000000;
0.000000;0.000000;
1.000000;0.000000;
0.000000;0.000000;
1.000000;0.000000;;
}
}


テクスチャの追加

テクスチャを追加するには、ファイル フォーマットの階層構造的な性質を使って、オプションの TextureFilename データ オブジェクトを Material データ オブジェクトに追加する。Material オブジェクトは次のようになる。

Material RedMaterial {
1.000000;0.000000;0.000000;1.000000;;    // R = 0.0, G = 1.0, B = 0.0
0.000000;
0.000000;0.000000;0.000000;;
0.000000;0.000000;0.000000;;
TextureFilename {
"tex1.ppm";
}
}
Material GreenMaterial {
0.000000;1.000000;0.000000;1.000000;;     // R = 0.0, G = 1.0, B = 0.0
0.000000;
0.000000;0.000000;0.000000;;
0.000000;0.000000;0.000000;;
TextureFilename {
"win95.ppm";
}
}


フレームとアニメーションの追加

ここでは、単純なキューブにフレームとアニメーションを追加する方法を説明する。

  • フレームの操作
  • AnimationSets とアニメーションの操作


フレームの操作

フレームは、次の構造を持たなければならない。

Frame Aframe {        // わかりやすいフレーム名を付ける。
FrameTransformMatrix {
...transform data...
}
[ Meshes ] and/or [ More frames]
}

定義済みのキューブ メッシュをフレーム内に置き、正規行列でトランスフォームする。その後、このフレームにアニメーションを適用する。

Frame CubeFrame {
FrameTransformMatrix {
1.000000, 0.000000, 0.000000, 0.000000,
0.000000, 1.000000, 0.000000, 0.000000,
0.000000, 0.000000, 1.000000, 0.000000,
0.000000, 0.000000, 0.000000, 1.000000;;
}
{CubeMesh}        // メッシュをインラインに置くこともできるが、
                  // ここではオブジェクト参照を使用する。
}


AnimationSets とアニメーションの操作

アニメーションは、一連のキーで定義する。キーとは、スケーリング処理、向き、または位置に関連付けられた、時間の値である。

Animation Animation0 {        // わかりやすい名前を付ける。
{ Frame that it applies to&em;normally a reference }
AnimationKey {
...animation key data...
}
{ ...more animation keys... }
}

アニメーションはその後 AnimationSets にグループ化される:

AnimationSet AnimationSet0 { // わかりやすい名前を付ける。
{ an animation?could be inline or a reference }
{ ... more animations ... }
}

ここで、アニメーション内でキューブを移動する。

AnimationSet AnimationSet0 {
Animation Animation0 {
{CubeFrame}    // キューブを含むフレームを使用する。
AnimationKey {
2;             // 位置座標キー。
9;             // 9 キー。
10; 3; -100.000000, 0.000000, 0.000000;;,
20; 3; -75.000000, 0.000000, 0.000000;;,
30; 3; -50.000000, 0.000000, 0.000000;;,
40; 3; -25.500000, 0.000000, 0.000000;;,
50; 3; 0.000000, 0.000000, 0.000000;;,
60; 3; 25.500000, 0.000000, 0.000000;;,
70; 3; 50.000000, 0.000000, 0.000000;;,
80; 3; 75.500000, 0.000000, 0.000000;;,
90; 3; 100.000000, 0.000000, 0.000000;;;
}
}
}

詳細については、Animation および AnimationSet テンプレートを参照すること。


3D モデルから X ファイルへの変換とエクスポート

Microsoft® Direct3D® は、3D モデルから .x ファイル フォーマットへ変換およびエクスポートするために次のツールを提供している。

  • Conv3ds.exe
  • XSkinExp.dle


Conv3ds.exe

Conv3ds.exe ユーティリティは、Autodesk 3-D Studio などのモデリング パッケージで作成した 3 次元 (3D) モデルを、Microsoft® DirectX® のファイル フォーマットに変換する。このユーティリティは、デフォルトではテンプレートなしでバイナリの .x ファイルを作成する。

説明するトピックは次のとおりである。

  • Conv3ds.exe の実行
  • Conv3ds.exe のオプション引数の指定
  • Lightwave オブジェクトからの 3DS ファイルの作成
  • ヒントとコツ


Conv3ds.exe の実行

Conv3ds.exe をオプションなしで実行すると、フレームの階層を含む .x ファイルが作成される。たとえば、次のコマンドを実行すると、.3ds ファイルから File.x という名前の .x ファイルが作成される。

conv3ds File.3ds

オプションを指定して Conv3ds.exe を実行する場合については、「Conv3ds.exe のオプション引数の指定」を参照すること。


Conv3ds.exe のオプション引数の指定

.3ds ファイルにキー フレーム データが含まれている場合は、-A オプションを使用すると、アニメーション セットを含む .x ファイルが作成される。コマンドの例を次に示す。

conv3ds -A File.3ds

File.3ds パラメータは、変換するファイルの名前である。

-m オプションを使用すると、.3ds ファイル内のすべてのオブジェクトから作成された 1 つのメッシュを含む x. ファイルが作成される。

conv3ds -m File.3ds

-T オプションを使用すると、すべてのオブジェクトとフレーム階層が 1 つの最上位フレーム内にラップされる。このオプションを使用することで、.3ds ファイル内のすべてのフレームとオブジェクトを 1 つの呼び出しでロードできる。.x ファイル内の、最初の最上位フレーム階層がロードされる。ほかのすべてのフレームとメッシュを含むフレームは、.3ds 拡張子なしで「x3ds_filename」と呼ばれる。-T オプションは、-m オプションと一緒に使った場合は効力がない。

-s オプションを使うと、.3ds ファイル内で変換されるすべてのオブジェクトのスケーリング係数を指定できる。たとえば、次のコマンドを実行すると、すべてのオブジェクトが 10 倍の大きさになる。

conv3ds -s10 File.3ds

次のコマンドを実行すると、すべてのオブジェクトが 10 分の 1 の大きさになる。

conv3ds -s0.1 File.3ds

-r オプションを使用すると、.3ds ファイルが変換されるときの面のワインディング順序が逆になる。.3ds ファイルを変換して Microsoft® Direct3D® で表示したときにオブジェクトが裏返しに表示される場合は、-r オプションを使って変換し直さなければならない。.3ds ファイルとしてエクスポートされた Lightwave モデルはすべてこのオプションを使って変換する必要がある。詳細については、「Lightwave オブジェクトからの 3DS ファイルの作成」を参照すること。

-v オプションを使用すると、冗長出力モードがオンになる。このオプションには整数を指定する。次の表は、現在サポートされている整数を示している。

オプション | 動作
-v0 | デフォルト。冗長モード オフ。
-v1 | 不正オブジェクトに関する警告を印刷し、コンバータの動作の一般的な情報も印刷する。
-v2 | 基本的なキー フレーム情報、変換処理に含まれるオブジェクト、および保存されるオブジェクトに関する情報を印刷する。
-v3 | 非常に冗長なモード。デバッグ情報を利用する際に最も有用。

-e オプションを使用すると、次の例に示すように、テクスチャ マップ ファイルの拡張子を変更できる。

conv3ds -e"ppm" File.3ds

File.3ds にテクスチャ マップ ファイル Brick.gif を参照するオブジェクトが含まれている場合、.x ファイルはテクスチャ マップ ファイル Brick.ppm を参照する。コンバータはテクスチャ マップ ファイルを変換しない。変換後の .x ファイルがロードされる際、テクスチャ マップ ファイルは D3DPATH に存在していなければならない。D3DPath は、デフォルトの検索パスを設定する環境変数である。

-x オプションを使用すると、バイナリ .x ファイルでなくテキスト .x ファイルが作成される。テキスト ファイルの方がサイズが大きくなるが、手作業で簡単に編集できる。

-X オプションを使用すると、ファイル内に .x ファイル テンプレートが強制的に含まれる。デフォルトでは、テンプレートは含まれない。

-t オプションを使用すると、変換後の .x ファイルにテクスチャ情報が含まれない。

-N オプションを使用すると、変換後の .x ファイルに法線ベクトル情報が含まれない。いずれかのロードの呼び出しを行うと、.x ファイル内に法線ベクトルを持たないオブジェクトの法線ベクトルが生成される。

-c オプションを使用すると、変換後の .x ファイルにテクスチャ座標が含まれない。.3ds オブジェクトがテクスチャ座標を持たない場合、デフォルトでは、-m オプションを使用すると、出力されるメッシュには (0,0) uv テクスチャ座標が含まれる。

-f オプションを使用すると、変換後の .x ファイルにフレーム トランスフォーム行列が含まれない。

-z および -Z オプションを使用すると、.x ファイル内のオブジェクトによって参照されているすべてのマテリアルのアルファ面カラー値を調整することができる。たとえば次のコマンドを実行すると、0.2 未満のすべてのアルファ値に 0.1 が加算される。

conv3ds -z0.1 -Z0.2 File.3ds

次のコマンドを実行すると、すべてのアルファについて、アルファ値から 0.2 が減算される。

conv3ds-z"-0.2" -z1 File.3ds

-o オプションを使用すると、変換後の .x ファイルの名前を指定できる。

-h オプションを使用すると、通常キー フレーマーによって作成される、.3ds ファイル内のいずれの階層情報も解決されない。その代わり、-m オプションが使用されない場合は、すべてのオブジェクトが最上位レベルのフレーム内に出力される。


Lightwave オブジェクトからの 3DS ファイルの作成

Lightwave の Trans3d プラグインによってエクスポートされた .3ds ファイルについては、いくつかの注意点がある。このようなファイルを最適な状態で変換するには、次の Conv3ds.exe コマンドを使用する。

conv3ds -r -N -f -h -T|m trans3dfile.3ds

Trans3d および Lightwave オブジェクト エディタによって作成された .3ds オブジェクトはすべて、ワインディング順序を逆にする必要がある。そうしないと、表示したときに裏返しの状態になる。これらのファイルには、サーフェス法線ベクトル情報は含まれていない。


ヒントとコツ

Conv3ds.exe によって作成されたオブジェクトをロードしても表示されない場合は、スケール オプション -s に約 100 のスケール係数を指定する。これにより、.x ファイル内でオブジェクトのスケールが増加する。

オブジェクトをビューア内にロードして、フラット シェーディングからグーロー シェーディングに切り替えたときに、オブジェクトが濃い灰色に変わった場合は、-N オプションを使って変換し直す。

オブジェクトの変換後に、テクスチャがロードされない場合は、オブジェクトが -e オプションを使って .ppm または .bmp ファイルを参照していないかどうか確認する。また、テクスチャの幅および高さが 2 の累乗になっていることを確認する。さらに、テクスチャが D3DPATH のディレクトリに格納されていることを確認する。

現在、Conv3ds.exe は .3ds アニメーションで使われるダミー フレームをサポートしていないため、ダミー フレームは無視される。ただし、子オブジェクトはすべて変換される。


XSkinExp.dle

XSkinExp.dle は extras ディレクトリにある。これは 3dsmax のエクスポータとして使用される。使用方法については、XSkinExp.dle に付属する readme ファイルを参照すること。


プログラミングのヒントおよびツール

ここでは、Microsoft® DirectX® Graphics アプリケーションを効率的に開発するための情報を記述する。説明するトピックは、次のとおりである。

  • トラブルシューティング
  • パフォーマンスの最適化
  • マルチスレッド処理の問題
  • デバイス ウィンドウの処理
  • 以前のドライバの処理
  • マルチモニタ システムの処理
  • ウィンドウ モードのマルチビュー


トラブルシューティング

ここでは、Microsoft® Direct3D® アプリケーションの開発中に発生する可能性がある問題を一般的なカテゴリ別に示し、その回避方法について説明する。

  • デバイスの作成
  • ライティング済み頂点の使い方
  • 何も表示されない
  • デバッグ
  • ボーランド浮動小数点初期化
  • パラメータの妥当性検査


デバイスの作成

デバイスの作成中にアプリケーションが異常終了した場合、次の共通のエラーを調べる。

  • デバイス能力、特にレンダリング深度を調べる。
  • エラー コードを調べる。D3DERR_OUTOFVIDEOMEMORY にエラーがあると考えられる。
  • デバッグ DirectX DLL を使用して、デバッガに表示される出力メッセージを確認する。


ライティング済み頂点の使い方

D3DLVERTEX 型に類似するライティング済み頂点を使用するアプリケーションの場合、D3DRS_LIGHTING レンダリング ステートを FALSE に設定して、Microsoft® Direct3D® ライティング エンジンを無効にする必要がある。デフォルトでは、ライティングは有効になっており、入力頂点にゼロ以外のカラー値が含まれていても、システムは法線ベクトルを含んでいない頂点の色を 0 (黒) に設定する。本来、ライティング済み頂点 (D3DLVERTEX など) には頂点法線が含まれないので、ライティング エンジンが有効になっていると、Direct3D に渡される色情報はレンダリングの際にすべて失われる。

独自のラインティングを実行するアプリケーションにとって、頂点カラーが重要であることは言うまでもない。システムによるデフォルト値の使用を回避するために、D3DRS_LIGHTING を FALSE に設定すること。


何も表示されない

アプリケーションを実行しても何も表示されない場合、次の共通のエラーを調べる。

  • 三角形がなくなっていないことを確認する。
  • 三角形がカリングされていないことを確認する。
  • トランスフォームが内部的に一貫していることを確認する。
  • ビューポートの設定を調べて、三角形の表示が可能になっていることを確認する。


デバッグ

注 ここでは、C/C++ でのアプリケーション開発について説明する。


ボーランド浮動小数点初期化

注 ここでは、C/C++ でのアプリケーション開発について説明する。


パラメータの妥当性検査

注 ここでは、C/C++ でのアプリケーション開発について説明する。


パフォーマンスの最適化

3D グラフィックスを使用するリアルタイム アプリケーションの開発者にとって、パフォーマンスの最適化は関心事の 1 つである。ここでは、最高のパフォーマンスが得られるコードを記述するにあたってのガイドラインについて説明する。

次のトピックで説明するガイドラインは、すべての Microsoft® Direct3D® アプリケーションに対して使用できる。

  • パフォーマンスに関する一般的なヒント
  • データベースおよびカリング
  • プリミティブのバッチ処理
  • ライティングに関するヒント
  • テクスチャ サイズ
  • 動的な頂点およびインデックス バッファの使い方
  • メッシュの使い方
  • Z バッファのパフォーマンス
  • 頂点シェーダの最適化


パフォーマンスに関する一般的なヒント

いくつかの一般的なガイドラインに従って、アプリケーションのパフォーマンスを向上させることができる。

  • クリア処理は必要なときにだけ行う。
  • ステートの変更は最小限に抑える。
  • パースペクティブ補正は必要なときにだけ使用する。
  • できるだけ小さなテクスチャを使用する。
  • システム リソースの共有のバランスを崩すような特殊効果はなるべく使用しない。
  • アプリケーションのパフォーマンスを絶えずテストする。
  • ハードウェア アクセラレーションとソフトウェア エミュレーションの両方でアプリケーションが正常に実行されることを確認する。


データベースおよびカリング

Microsoft® Direct3D® の優れたパフォーマンスを実現するための鍵となるのは、ワールド内のオブジェクトを収める信頼性あるデータベースを構築することである。これはラスタ化やハードウェアの改善より重要なことである。

ポリゴンの個数は、管理できる範囲内で最小限に抑える必要がある。ポリゴンの個数を少なくするには、最初からその個数が少なくて済むようなモデルを構築する。ポリゴンの追加は、開発段階の後半で、パフォーマンスを犠牲にせずに追加できる場合に行う。最速のポリゴンは描画しないポリゴンであることを覚えておく。


プリミティブのバッチ処理

実行時に最高のレンダリング パフォーマンスを得るには、プリミティブをバッチ処理し、レンダリングステートの変更回数をできるだけ少なくする。たとえば、1 つのオブジェクトで 2 つのテクスチャを使用している場合、最初のテクスチャを使用する三角形をグループ化し、必要なレンダリング ステートをその三角形に付加してテクスチャを変更する。次に、もう 1 つのテクスチャを使用する三角形をすべてグループ化する。Microsoft® Direct3D® の最も単純なハードウェア サポートは、Hardware Abstraction Layer (HAL) を介して、レンダリング ステートのバッチおよびプリミティブのバッチによって呼び出される。命令のバッチ処理を効率的に行えば、実行時の HAL の呼び出し回数が減少する。


ライティングに関するヒント

ライトを適用した場合、レンダリングされる各フレームに頂点ごとの負荷が加わる。したがって、アプリケーションでライトを慎重に使用すれば、パフォーマンスの大幅な向上が見込める。次のヒントのほとんどは、最速のコードは呼び出されないコードであるという考えに基づく。

  • 光源は必要最小限で使用する。全体的なライティング レベルを増加させることだけが必要な場合は、新しい光源を追加するのではなく、アンビエント ライトを使用する。負担がずっと軽くなる。
  • ディレクショナル ライトは、ポイント ライトやスポットライトより負担が軽い。ディレクショナル ライトの場合、光の方向が固定されているため、頂点ごとに計算する必要がない。
  • スポットライトは、ポイント ライトより負担が軽い。光のコーンの外側の領域の計算はすばやく行われるためである。スポットライトの負担が軽いかどうかは、スポットライトでシーンを照らす量によって異なる。
  • 範囲パラメータを使用して、必要な部分にだけライトを照らす。範囲外にあるすべてのライトのタイプはすぐに終了する。
  • スペキュラ ハイライトは、負担がおよそ 2 倍になるため、必要なときにだけ使用する。D3DRS_SPECULARENABLE レンダリング ステートには、できるだけデフォルト値 0 を設定する。マテリアルを定義するときは、スペキュラ強度値をゼロに設定して、そのマテリアルに対するスペキュラ ハイライトをオフにする。単にスペキュラ色を 0,0,0 に設定するだけでは不十分である。


テクスチャ サイズ

テクスチャ マッピングのパフォーマンスは、メモリの速度に大きく依存する。アプリケーションのテクスチャをキャッシュする際のパフォーマンスを最大限に高める方法がいくつかある。

  • テクスチャは小さくする。テクスチャが小さければ、メイン CPU の 2 次キャッシュに格納される可能性が高くなる。
  • プリミティブごとにテクスチャを変更しない。ポリゴンは使用するテクスチャの順にグループ化する。
  • できるだけ正方形テクスチャを使用する。寸法が 256 × 256 のテクスチャが最速である。たとえば、アプリケーションで 128 × 128 の 4 つのテクスチャを使用する場合、これらのテクスチャで同じパレットを使い、すべてのテクスチャを 256 × 256 の 1 つのテクスチャに配置する。この方法を使用すると、テクスチャのスワップ量も減少する。もちろん、上で説明したように、テクスチャはできるだけ小さくする必要があるので、アプリケーションで 256 × 256 のテクスチャが必要な場合を除いては、そのようなテクスチャを使用してはならない。


動的な頂点およびインデックス バッファの使い方

動的な頂点およびインデックス バッファには、サイズと使用方法に基づいてパフォーマンスに違いがある。次の使用方法を参考に、Lock メソッドの Flags パラメータに D3DLOCK_DISCARD を使用するか、または D3DLOCK_NOOVERWRITE を使用するかを判断する。

使用方法 1 :

for loop()
{
    pBuffer->Lock(...D3DLOCK_DISCARD...); // 新しいポインタを返して、
                                          // ハードウェアが機能停止しないことを
                                          // 保証する。
    Fill data (optimally 1000s of vertices/indices, no fewer) in pBuffer.
    pBuffer->Unlock()
    Change state(s).
    DrawPrimitive() or DrawIndexedPrimitive()
}

使用方法 2 :

for loop()
{
    pVB->Lock(...D3DLOCK_DISCARD...);//新しいポインタが返ることによって
                                      //ハードウェアがストールしない
                                      //ようにする。
    Fill data (optimally 1000s of vertices/indices, no fewer) in pBuffer.
    pBuffer->Unlock
    for loop( 100s of times )
    {
        Change State
        DrawPrimitive() or DrawIndexPrimitives() //Tens of primitives
    }
}

使用方法 3 :

for loop()
{
    If there is space in the Buffer
    {
        // 頂点やインデックスを追加する。
        pBuffer->Lock(�D3DLOCK_NOOVERWRITE�);
    }
    Else
    {
        // 先頭に戻る。
        pBuffer->Lock(�D3DLOCK_DISCARD�);
    }
    Fill few 10s of vertices/indices in pBuffer
    pBuffer->Unlock
    Change State
    DrawPrimitive() or DrawIndexedPrimitive() // 数個のプリミティブ。

}

使用方法 1 は、使用方法 2 または 3 より処理は速いが、一般的には実用に向かない。アプリケーションで各 Lock に対して平均 2、3000 個の頂点やインデックスを追加する場合、使用方法 2 の方が使用方法 3 より処理が速い。平均より少ない場合には、使用方法 3 の方が速い。どの Lock メソッドが高速であるかに関しては確かな答えはなく、いろいろな方法を試すことで最善の方法を見つける。


メッシュの使い方

メッシュを最適化するには、Microsoft® Direct3D® のインデックス付き三角形ストリップではなく、インデックス付き三角形を使用する。ハードウェアは、連続する三角形の 95% が実際にストリップを形成しているものとして検出し、それに応じて調整を行う。多くのドライバは、レガシー ハードウェアに対してもこのような処理を行う。

以下に、メッシュのさまざまな属性について示す。

属性 ID

属性 ID は、面のグループを属性グループに関連付ける値である。この ID は、DrawSubset で描画する面のサブセットを記述する。属性 ID は、属性バッファ内の面に対して指定される。属性 ID の実際の値は、32 ビットに適合すればどのような値でもかまわないが、一般には 0 ～ n (属性数) を使用する。

属性バッファ

属性バッファは、各面が属する属性グループを指定する DWORD (各面に 1 つ) の配列である。このバッファは、メッシュの作成時にゼロに初期化されるが、ロード ルーチンによって値を指定するか、ID 0 の属性が複数個必要な場合にはユーザーによって指定するかのいずれかの必要がある。このバッファには、Optimize で属性に基づいてメッシュをソートするために使用する情報が格納される。属性テーブルが提示されていない場合、DrawSubset はこのバッファを調べて、描画する指定の属性の面を選択する。

属性テーブル

属性テーブルは、メッシュによって所有および保持される構造体である。これを生成するには、属性ソート機能または最適化の強化機能を有効にして Optimize を呼び出す必要がある。属性テーブルは、プリミティブを描画する単一の呼び出しを DrawSubset にすばやく初期化するために使用される。また、プログレッシブ メッシュもこの構造体を保持するので、現在の詳細レベル (LOD) でアクティブな面と頂点を表示することができる。


Z バッファのパフォーマンス

シーンが前から後にレンダリングされるように、z バッファリングを使用してテクスチャ処理を行うと、アプリケーションのパフォーマンスを向上させることができる。テクスチャを適用し、z バッファを使用したプリミティブは、走査線単位で z バッファについて事前にテストされる。前にレンダリングされたポリゴンによって走査線が隠れている場合は、そのポリゴンがシステムによってすばやく効率的に除去される。z バッファリングによってパフォーマンスは向上するが、この手法はシーンでオーバードローを何度も行うときに最も有効である。オーバードローとは、スクリーン ピクセルの平均書き込み回数である。オーバードローを正確に計算するのは難しいが、近似値を求めることはできる。オーバードローの平均が 2 より小さい場合には、z バッファリングをオフにし、シーンを後から前にレンダリンすると、最高のパフォーマンスが得られる。

高速なパーソナル コンピュータの場合、ソフトウェアによるシステム メモリへのレンダリングの方が、ビデオ メモリへのレンダリングより高速であることが多い。ただし、この場合、ダブル バッファリングやハードウェア アクセラレーションによるクリア処理は使用できない。アプリケーションでシステム メモリまたはビデオ メモリのいずれにもレンダリングでき、どちらが高速であるかをテストするルーチンがあれば、現在のシステムで最適な方法を利用することができる。Microsoft® Direct3D® の SDK に収録されるサンプル コードでは、この方法を示している。速度をテストする方法がほかにないため、両方の方法を実装する必要がある。速度はコンピュータ間で大きく異なり、メインメモリ アーキテクチャや、使用するグラフィックス アダプタの種類に依存する。


頂点シェーダの最適化

頂点シェーダを最適化するには、次に示すようにいくつかの方法がある。

  • 頂点バッファのスイッチを最小化すること。
  • 可能なら静的頂点バッファを使うこと。
  • オブジェクトごとではなく、静的オブジェクトに対して FVF ごとに 1 つの大きな頂点バッファを使うこと。
  • シェーダ内で必要でないなら、出力レジスタをコピーしない。

たとえば、

       mad r1,c[2],c[3]
       mov oD0, r1

ではなく、次のようにする。

       mad oD0, r1, c[2], c[3]


マルチスレッド処理の問題

ここでは、C++ でのアプリケーション開発について説明する。


デバイス ウィンドウの処理

ここでは、C++ でのアプリケーション開発について説明する。


以前のドライバの処理

ここでは、DirectX 8.0 以前のバージョンの DirectX 用に作成されたドライバ上で Microsoft® DirectX® 8.0 を処理する場合に発生する可能性のある問題を示す。

  • TnLHAL デバイスを処理する場合、フォグの強度は計算されるが、この値に絶対値演算は適用されない。計算結果が負の場合、値は負のままである。このような状況を回避する最善の方法は、トランスフォームを正しく設定することである。次善の策としては、フォグの開始値とフォグの終了値を負になるようにする方法がある。

D3DCAPS8 の MaxStream メンバを照会することで、ドライバが DirectX 8.0 用に作成されていないことを検出できる。この値が 0 である場合、ドライバは DirectX 8.0 ドライバではない。


マルチモニタ システムの処理

排他的なフルスクリーン モードの概念が Microsoft® DirectX® 8.0 に保持されているが、Direct3D8.CreateDevice および Direct3DDevice8.Resetメソッドの呼び出しでは完全に非明示的に保持される。フルスクリーン処理でデバイスのリセットまたは作成が正常に行われると、そのデバイスを作成した Direct3D8 オブジェクトがシステム上のすべてのアダプタを所有しているものとしてマークされる。この状態は排他モードと呼ばれ、この時点で Direct3D8 オブジェクトは排他モードを所有している。排他モードでは、ほかの Direct3D8 オブジェクトによって作成されたデバイスがフルスクリーン処理を行ったりビデオ メモリを割り当てることはできない。また、Direct3D8 オブジェクトが排他モードであると見なしたときには、フルスクリーンになったデバイス以外のデバイスはすべて消失状態になる。消失したデバイスを処理する方法については、「消失したデバイス」を参照すること。

排他モードでは、その Direct3D8 オブジェクトに、デバイスが使用するフォーカス ウィンドウが通知される。その Direct3D8 オブジェクトが所有する最後のフルスクリーン デバイスがウィンドウ モードにリセットされるか破壊されると、排他モードは解放される。

Direct3D8 オブジェクトが排他モードを所有するとき、デバイスは 2 つのカテゴリに分類される。最初のカテゴリのデバイスは、既にフルスクリーンであるデバイスを作成したものと同じ Direct3D8 オブジェクトによって作成され、既にフルスクリーンであるデバイスと同じフォーカス ウィンドウを持ち、ほかのフルスクリーン デバイスとは別のアダプタを表す。このカテゴリのデバイスは、制限なく Reset または作成でき、消失状態になることはない。このカテゴリのデバイスは、フルスクリーン モードにすることもできる。

このカテゴリに入らないデバイス (別の Direct3D8 オブジェクトによって作成されたか、別のフォーカス ウィンドウで作成されたか、既にフルスクリーンのデイバイスがあるアダプタに作成されたデバイス) はリセットできず、排他モードがなくなるまで消失状態のままになる。

実際には、マルチモニタ アプリケーションでは複数のデバイスをフルスクリーン モードにすることができるが、それは、これらのデバイスがすべて異なるアダプタのデバイスであり、同じ Direct3D8 オブジェクトによって作成され、しかも同じフォーカス ウィンドウを共有する場合に限られる。


ウィンドウ モードのマルチビュー

Direct3DDevice8 インターフェイスを介して所有し操作できるスワップ チェーンに加えて、同じデバイスから複数のビューに提示するための追加スワップ チェーンを作成できる。アプリケーションは、一般的に、Direct3DDevice8.CreateAdditionalSwapChain メソッドを使用してビューごとに 1 つのスワップ チェーンを作成し、そのスワップ チェーンを特定のウィンドウに関連付ける。アプリケーションは、各スワップ チェーンのバック バッファにイメージをレンダリングした後、個々に提示する。

各アダプタでは一度に 1 つのスワップ チェーンしかフルスクリーンにできない。


DirectX Graphics Visual Basic チュートリアル

ここでは、Microsoft Visual Basic® アプリケーションで Microsoft® Direct3D® および Direct3DX を使用する方法について、共通のタスクの各タスクを必要なステップに分けて説明する。場合によっては、理解しやすくするために、ステップがさらに細かいステップに分かれている。次のチュートリアルを提供する。

  • チュートリアル 1 : デバイスの作成
  • チュートリアル 2 : 頂点のレンダリング
  • チュートリアル 3 : 行列の使い方
  • チュートリアル 4 : ライトの作成および使い方
  • チュートリアル 5 : テクスチャ マップの使い方
  • チュートリアル 6 : メッシュの使い方

注 これらのチュートリアルのサンプル コードはソース プロジェクトに含まれており、その場所は各チュートリアルに示されている。

添付されているサンプル コード中のコメントには、SDK のソース ファイルとは異なるものもある。変更は、コードの動作が変わるのを避けるため、コメントだけに限定し、簡潔にするためだけに行っている。

参照

DirectX Graphics Visual Basic サンプル


チュートリアル 1 : デバイスの作成

Microsoft Visual Basic® で Microsoft® Direct3D® を使用するには、まず、アプリケーション ウィンドウのフォームを作成した後、Direct3D オブジェクトを作成して初期化する。これらのオブジェクトは、定義済みのメソッドによって操作する。また、これらのメソッドを使って、シーンのレンダリングに必要な従属オブジェクトを作成する。このチュートリアルで使用するサンプル プロジェクト CreateDevice では、Direct3D デバイスを作成し、青い画面をレンダリングすることによって、このタスクを示す。このチュートリアルでは、次のステップで、フォームを作成し、Direct3D を設定し、シーンをレンダリングして、最後にシャット ダウンを行う。

  • ステップ 1 : フォームの作成
  • ステップ 2 : Direct3D の初期化
  • ステップ 3 : シーンのレンダリングおよび表示
  • ステップ 4 : シャット ダウン

注 CreateDevice サンプル プロジェクトのパスは次のとおりである。

(SDK ルート)\Samples\Multimedia\VBSamples\Direct3D\Tutorials\Tut01_CreateDevice


ステップ 1 : フォームの作成

Microsoft® Visual Basic® のフォームは、アプリケーション ウィンドウの役割を果たす。次の方法でフォームのプロパティを設定する。

BorderStyle     =   2 - Sizeable
Caption         =   "Create Device"
Height          =   3600
Left            =   0
Top             =   0
Width           =   4800
LinkTopic       =   "Form1"
MaxButton       =   True
MinButton       =   True
ScaleHeight     =   3195
ScaleMode       =   1 - Twip
ScaleWidth      =   254
StartUpPosition =   3 - Windows Default

アプリケーション ウィンドウを表示するには、Form_Load プロシージャに次の行を追加する。

Me.Show

アプリケーション ウィンドウが準備できると、Microsoft DirectX® の主要オブジェクトの初期化を開始することができる。これについては、「ステップ 2 : Direct3D の初期化」で説明する。


ステップ 2 : Direct3D の初期化

CreateDevice サンプル プロジェクトでは、フォームを表示した後、Form_Load から呼び出されるアプリケーション定義関数 InitD3D でシステムの初期化を実行する。アプリケーションのフォームを表示すると、Microsoft® Direct3D® デバイスの初期化を開始できる。このデバイスを使ってシーンのレンダリングを行う。この処理には、Direct3D オブジェクトの作成、プレゼンテーション パラメータの設定、および Direct3D デバイスの作成が含まれる。

Direct3D オブジェクトを作成するには、DirectX8.Direct3DCreate メソッドを使用する。この Direct3D オブジェクトを使って、デバイス、タイプ、モードなどを列挙することもできる。

Set g_D3D = g_DX.Direct3DCreate()
If g_D3D Is Nothing Then Exit Function

次のステップでは、Direct3D8.GetAdapterDisplayMode メソッドを使用して現在のディスプレイ モードを検出する。次のコードに、その処理を示す。

Dim Mode As D3DDISPLAYMODE
g_D3D.GetAdapterDisplayMode D3DADAPTER_DEFAULT, mode

Direct3D デバイスを作成するときは、D3DDISPLAYMODE 構造体の Format メンバが使用される。ウィンドウ モードで実行する場合は、アダプタの現在のモードと一致するバック バッファを作成するために Format メンバが使用される。

D3DPRESENT_PARAMETERS オブジェクトのフィールドに入力することによって、3D アプリケーションの動作を指定できる。CreateDevice サンプル プロジェクトでは、Windowed メンバを 1 (TRUE)、SwapEffect メンバを D3DSWAPEFFECT_COPY_VSYNC、BackBufferFormat メンバに mode.Format を設定している。

Dim d3dpp As D3DPRESENT_PARAMETERS
d3dpp.Windowed = 1
d3dpp.SwapEffect = D3DSWAPEFFECT_COPY_VSYNC
d3dpp.BackBufferFormat = mode.Format

最後のステップは、次のコード例に示されているように、Direct3D8.CreateDevice メソッドを使って Direct3D デバイスを作成することである。

Set g_D3DDevice = g_D3D.CreateDevice(D3DADAPTER_DEFAULT, D3DDEVTYPE_HAL, hWnd, _
                                     D3DCREATE_SOFTWARE_VERTEXPROCESSING, d3dpp)
If g_D3DDevice Is Nothing Then Exit Function

上記のコードでは、D3DADAPTER_DEFAULT フラグを使って、デフォルトのアダプタを指定してデバイスを作成している。システムに複数のグラフィックス ハードウェア カードがインストールされていない限り、ほとんどの場合、システムのアダプタは 1 つだけである。ハードウェア デバイスをソフトウェア デバイスよりも優先することを指定するには、DeviceType パラメータに D3DDEVTYPE_HAL を指定する。このサンプルでは、D3DCREATE_SOFTWARE_VERTEXPROCESSING を使って、ソフトウェア頂点処理を使用することをシステムに指示している。D3DCREATE_HARDWARE_VERTEXPROCESSING を指定してハードウェア頂点処理を使用することをシステムに指示した場合、ハードウェア頂点処理をサポートするビデオ カードではパフォーマンスが大幅に向上することに注意すること。

必要な Direct3D オブジェクトが作成されたので、次のステップでは、レンダリング ループを実行する。これについては、「ステップ 3 : シーンのレンダリングおよび表示」で説明する。


ステップ 3 : シーンのレンダリングおよび表示

CreateDevice サンプル プロジェクトでは、タイマを使って特定の間隔で画面をレンダリングする。このサンプルでは、タイマの Interval プロパティを 40 に設定する。これは、40 ミリ秒おきに関数 Timer1_Timer が呼び出されることを意味する。タイマが実行されると、アプリケーション定義関数 Render を呼び出して、シーンをレンダリングして表示する。CreateDevice サンプル プロジェクトでは、バック バッファを青色にクリアし、バック バッファの内容をフロント バッファに転送して、フロント バッファを画面に表示している。

シーンをレンダリングするには、Direct3DDevice8.Clear メソッドを呼び出して開始する。

g_D3DDevice.Clear 0, ByVal 0, D3DCLEAR_TARGET, &HFF&, 1#, 0

Clear が受け取る最初の 2 つのパラメータは、Microsoft® Direct3D® に、クリアする矩形の配列のサイズとアドレスを通知する。矩形の配列は、レンダリング ターゲット サーフェス上のクリアする領域を記述する。

通常、レンダリング ターゲット全体を覆う 1 つの矩形を使用する。これは、最初のパラメータを 0 に設定し、2 番目のパラメータを ByVal 0 に設定することによって行われる。3 番目のパラメータは、メソッドの動作を決める。レンダリング ターゲット サーフェス、関連深度バッファ、ステンシル バッファ、またはこの 3 つの任意の組み合わせをクリアすることができる。このチュートリアルでは、深度バッファを使用しないので、D3DCLEAR_TARGET 以外のフラグは使用しない。最後の 3 つのパラメータは、レンダリング ターゲット、深度バッファ、ステンシル バッファのクリア値を反映するように設定する。CreateDevice サンプル プロジェクトでは、レンダリング ターゲット サーフェスのクリア カラーを青 (&HFF&) に設定している。最後の 2 つのパラメータは、対応するフラグが存在しないので、Clear メソッドで無視される。

ビューポートをクリアした後、CreateDevice サンプル プロジェクトは、次のコードに示すように、レンダリングの開始およびレンダリングの終了を Direct3D に通知する。

' シーンを開始する。
g_D3DDevice.BeginScene

' ここで、シーンのオブジェクトをレンダリングする。

' シーンを終了する。
g_D3DDevice.EndScene

Direct3DDevice8.BeginScene および Direct3DDevice8.EndScene メソッドは、レンダリングの開始時および終了時をそれぞれシステムに通知する。レンダリング メソッドは、この 2 つのメソッドの呼び出しの間でしか呼び出すことができない。レンダリング メソッドが正常に終了しなかった場合でも、BeginScene を再度呼び出す前に、EndScene を呼び出す必要がある。

シーンをレンダリングしたら、Direct3DDevice8.Present メソッドを使ってシーンを表示する。

g_D3DDevice.Present ByVal 0, ByVal 0, 0, ByVal 0

Present が受け取る最初の 2 つのパラメータは、転送元矩形と転送先矩形である。このサンプルでは、これら 2 つのパラメータを ByVal 0 に設定して、バック バッファ全体をフロント バッファに渡す。3 番目のパラメータは、このプレゼンテーション用のターゲット ウィンドウを設定する。このパラメータは 0 に設定されているので、D3DPRESENT_PARAMETERS の hWndDeviceWindow メンバが使用される。4 番目のパラメータは DirtyRegion パラメータで、ほとんどの場合 ByVal 0 に設定する必要がある。

このチュートリアルの最後のステップは、アプリケーションの終了である。これについては、「ステップ 4 : シャット ダウン」で説明する。


ステップ 4 : シャット ダウン

アプリケーションは、実行中のある時点で、シャット ダウンしなければならない。Microsoft® DirectX® アプリケーションをシャット ダウンする場合は、アプリケーションが使用した DirectX オブジェクトに Nothing を設定して、関連付けを解除する必要がある。CreateDevice サンプル プロジェクトでは、このクリーンアップを処理するアプリケーション定義関数 Cleanup を呼び出す。Cleanup は、フォームをアンロードするときに、Form_Unload から呼び出される。

Private Sub Form_Unload(Cancel As Integer)

    Set g_D3D = Nothing
    Set g_D3DDevice = Nothing

End Sub

上記の関数は、Microsoft Direct3D® オブジェクトを Nothing に設定し、実際のオブジェクトから変数の関連付けを解除している。シャット ダウンするとき以外にも、ユーザーがデスクトップ解像度や色深度を変更したときなどの通常の実行時に、使用中の Direct3D オブジェクトを破棄して再作成する必要が生じることもある。したがって、必要な場合に呼び出すことができるよう、アプリケーションのクリーンアップ コードを 1 か所に保持しておくと便利である。

このチュートリアルでは、デバイスの作成方法を示した。「チュートリアル 2 : 頂点のレンダリング」では、頂点を使用してジオメトリ形状を描画する方法を示す。


チュートリアル 2 : 頂点のレンダリング

Microsoft® Direct3D® で作成されたアプリケーションでは、頂点を使ってジオメトリ形状を描画する。各 3D シーンには、このようなジオメトリ形状が 1 つまたは複数含まれる。Vertices サンプル プロジェクトでは、最も単純な図形である三角形を作成し、ディスプレイにレンダリングする。このチュートリアルでは、カスタム頂点タイプの選択、頂点バッファの設定、頂点のレンダリングおよび表示の方法について説明する。

このチュートリアルでは、次のステップで、頂点を使って三角形を作成する方法を示す。

  • ステップ 1 : カスタム頂点タイプの定義
  • ステップ 2 : 頂点バッファの設定
  • ステップ 3 : ディスプレイのレンダリング

注 Vertices サンプル プロジェクトのパスは次のとおりである。

(SDK ルート)\Samples\Multimedia\VBSamples\Direct3D\Tutorials\Tut01_Vertices

Vertices サンプル プロジェクトのコードは、CreateDevice サンプル プロジェクトのコードとほぼ同じである。このチュートリアルでは、頂点に固有のコードのみに注目し、Direct3D の初期化、レンダリング、またはシャット ダウンについては説明しない。これらのタスクについては、「チュートリアル 1 : デバイスの作成」を参照すること。


ステップ 1 : カスタム頂点タイプの定義

Vertices サンプル プロジェクトでは、3 つの頂点を使って 2D の三角形をレンダリングする。ここでは、頂点を格納およびレンダリングするために使用される Microsoft® Direct3D® オブジェクトである、頂点バッファの概念を導入している。頂点は、カスタム頂点構造体および対応するカスタム FVF (柔軟な頂点フォーマット) を指定することによって、多くの方法で定義できる。Vertices サンプル プロジェクトの頂点のフォーマットを、次のコードに示す。

Private Type CUSTOMVERTEX
    x As Single         'スクリーン空間での x
    y As Single         'スクリーン空間での y
    z As Single         '正規化された z
    rhw As Single       '正規化された rhw
    color As Long       '頂点カラー
End Type

上記の構造体は、カスタム頂点タイプのフォーマットを指定する。次のステップは、頂点バッファ内の頂点の内容を記述する FVF を定義することである。次のコードでは、上で作成したカスタム頂点タイプに対応する FVF を定義している。

Const D3DFVF_CUSTOMVERTEX = (D3DFVF_XYZRHW Or D3DFVF_DIFFUSE)

柔軟な頂点フォーマット フラグは、使用するカスタム頂点のタイプを指定する。Vertices サンプル プロジェクトでは、D3DFVF_XYZRHW および D3DFVF_DIFFUSE フラグを使用して、カスタム頂点タイプがトランスフォームされたポイントと色成分を持つことを頂点バッファに通知している。

カスタム ベクトル フォーマットおよび FVF が指定されたので、次のステップでは、頂点バッファに頂点を入力する。これについては、「ステップ 2 : 頂点バッファの設定」で説明する。

注 Vertices サンプル プロジェクトの頂点はトランスフォームされている。つまり、頂点は既に 2D ウィンドウ座標で表されている。これは、ポイント (0,0) が左上隅であり、正の x 軸が右方向、正の y 軸が下方向であることを意味する。これらの頂点にライトを当てることもできる。これは、頂点は Direct3D ライティングを使用していないが、独自の色を提供していることを意味する。


ステップ 2 : 頂点バッファの設定

カスタム頂点フォーマットが定義されたので、次は頂点を初期化する。Vertices サンプル プロジェクトでは、この処理を行うために、必要な Microsoft® Direct3D® オブジェクトを作成した後、アプリケーション定義関数 InitVB を呼び出している。次のコードでは、3 つのカスタム頂点の値を初期化している。

With Vertices(0): .x = 150: .y =  50: .z = 0.5: .rhw = 1: .color = &HFFFF0000: End With
With Vertices(1): .x = 250: .y = 250: .z = 0.5: .rhw = 1: .color = &HFF00FF00: End With
With Vertices(2): .x =  50: .y = 250: .z = 0.5: .rhw = 1: .color = &HFF00FFFF: End With

上記のコードでは、3 つの頂点に三角形のポイントを設定し、各頂点が放射する色を指定する。最初のポイントは (150, 50) にあり、赤色 (&HFFFF0000) を放射する。2 番目のポイントは (250, 250) にあり、緑色 (&HFF00FF00) を放射する。3 番目のポイントは (50, 250) にあり、青緑色 (&HFF00FFFF) を放射する。これら各ポイントのピクセル深度は 0.5、RHW は 1 である。このベクトル フォーマットの詳細については、「トランスフォーム済み ライティング済みの頂点」を参照すること。

次のステップは、次のコードのように、Direct3DDevice8.CreateVertexBuffer を呼び出して頂点バッファを作成することである。

Set g_VB = g_D3DDevice.CreateVertexBuffer(VertexSizeInBytes * 3, _
                 0, D3DFVF_CUSTOMVERTEX, D3DPOOL_DEFAULT)
If g_VB Is Nothing Then Exit Function

CreateVertexBuffer の最初の 2 つのパラメータは、新しい頂点バッファの必要なサイズと使用方法を Direct3D に指示する。次の 2 つのパラメータは、新しいバッファのベクトル フォーマットおよびメモリ領域を指定する。ベクトル フォーマットは、Vertices サンプル プロジェクトで以前に指定された FVF である D3DFVF_CUSTOMVERTEX である。D3DPOOL_DEFAULT フラグは、頂点バッファを、このバッファに最も適したメモリに作成するよう Direct3D に指示する。最後のパラメータは、作成する頂点バッファのアドレスである。

頂点バッファを作成した後、次のコードのように D3DVertexBuffer8SetData メソッドを呼び出すことによって、このバッファにカスタム頂点のデータが設定される。

D3DVertexBuffer8SetData g_VB, 0, VertexSizeInBytes * 3, 0, Vertices(0)

D3DVertexBuffer8SetData で使用する最初のパラメータは、データを格納する頂点バッファである。2 番目のパラメータは、データが設定されるバッファの先頭からのオフセット (バイト単位) である。3 番目のパラメータは、バッファのサイズをバイト単位で指定する。4 番目のパラメータは、バッファをロックする方法を記述する 1 つ以上のフラグの組み合わせである。このサンプルでは、このパラメータを 0 に設定し、デフォルトのフラグをロックに送信するよう関数に指示している。5 番目のパラメータは、頂点バッファに配置するデータを格納するバッファである。

頂点バッファに頂点が格納されたので、次はディスプレイをレンダリングする。これについては、「ステップ 3 : ディスプレイのレンダリング」で説明する。


ステップ 3 : ディスプレイのレンダリング

頂点バッファに頂点が格納されたので、次はディスプレイをレンダリングする。ディスプレイのレンダリングでは、まずバック バッファを青色にクリアした後、BeginScene を呼び出す。

g_D3DDevice.Clear 0, ByVal 0, D3DCLEAR_TARGET, &HFF&, 1#, 0
g_D3DDevice.BeginScene

頂点バッファの頂点のレンダリングは、いくつかのステップに分かれる。まず、ストリーム ソースを設定する。この場合は、ストリーム 0 を使用する。ストリームのソースは、Direct3DDevice8.SetStreamSource を呼び出して指定する。

g_D3DDevice.SetStreamSource 0, g_VB, sizeOfVertex

SetStreamSource の最初のパラメータは、Microsoft® Direct3D® にデバイス データ ストリームのソースを指示する。2 番目のパラメータは、データ ストリームにバインドする頂点バッファである。3 番目のパラメータは、コンポーネントのサイズをバイト単位で指定する。

次のステップは、Direct3DDevice8.SetVertexShader を呼び出して、使用する頂点シェーダを Direct3D に通知することである。完全なカスタム頂点シェーダは高度なトピックであるが、ほとんどの場合、頂点シェーダは単なる FVF である。これによって、処理する頂点のタイプが Direct3D に通知される。次のコードでは、頂点シェーダを設定している。

g_D3DDevice.SetVertexShader D3DFVF_CUSTOMVERTEX

SetVertexShader のパラメータは、使用する頂点シェーダへのハンドルだけである。このパラメータの値として、Direct3DDevice8.CreateVertexShader から返るハンドルまたは FVF コードを使用できる。ここでは、D3DFVF_CUSTOMVERTEX によって定義された FVF コードを使用している。

頂点シェーダの詳細については、「頂点シェーダ」を参照すること。

次のステップは、次のコードのように、Direct3DDevice8.DrawPrimitive を使って頂点バッファの頂点をレンダリングすることである。

g_D3DDevice.DrawPrimitive D3DPT_TRIANGLELIST, 0, 1

DrawPrimitive が受け取る最初のパラメータは、描画するプリミティブのタイプを Direct3D に指示するフラグである。このサンプルでは、D3DPT_TRIANGLELIST フラグを使って、三角形のリストを指定している。2 番目のパラメータは、ロードする最初の頂点のインデックスである。3 番目のパラメータは、描画するプリミティブの数を指定する。このサンプルでは、三角形を 1 つだけ描画するので、この値は 1 に設定される。

さまざまなプリミティブの詳細については、「3D プリミティブ」を参照すること。

最後のステップは、シーンを終了し、バック バッファをフロント バッファに表示することである。次のコードに、この処理を示す。

g_D3DDevice.EndScene
g_D3DDevice.Present ByVal 0, ByVal 0, 0, ByVal 0

バック バッファをフロント バッファに表示すると、クライアント ウィンドウに 3 種類の色のポイントを持つ三角形が表示される。

このチュートリアルでは、頂点を使ってジオメトリ形状をレンダリングする方法を示した。「チュートリアル 3 : 行列の使い方」では、行列の概念とその使用方法について説明する。


チュートリアル 3 : 行列の使い方

このチュートリアルでは、行列の概念とその使用方法を示す。Vertices サンプル プロジェクトでは、2D の頂点をレンダリングして三角形を描画した。ここでは、3D の頂点のトランスフォームを処理する。行列は、カメラとビューポートの設定にも使用される。トランスフォーム行列の処理の詳細については、「3D トランスフォーム」を参照すること。

Matrices サンプル プロジェクトでは、ジオメトリをレンダリングする前に、3D の三角形のレンダリングに使用する行列トランスフォームを作成および設定するアプリケーション定義関数 SetupMatrices を呼び出す。通常、3D シーンには 3 つのタイプのトランスフォームが適用される。この一般的なトランスフォームを作成するステップを、以下に示す。

  • ステップ 1 : ワールド トランスフォーム行列の定義
  • ステップ 2 : ビュー トランスフォーム行列の定義
  • ステップ 3 : 射影トランスフォーム行列の定義

行列およびトランスフォームの詳細については、「行列」を参照すること。

3D トランスフォームの詳細については、「3D トランスフォーム」を参照すること。

注 Matrices サンプル プロジェクトのパスは次のとおりである。

(SDK ルート)\Samples\Multimedia\VBSamples\Direct3D\Tutorials\Tut03_Matrices

トランスフォーム行列を作成する順序は、シーン内のオブジェクトのレイアウトには影響しない。ただし、Direct3D では、(1) ワールド、(2) ビュー、(3) 射影の順序で、シーンに行列が適用される。

Matrices サンプル プロジェクトのコードは、Vertices サンプル プロジェクトのコードとほぼ同じである。このチュートリアルでは、行列に固有のコードのみに注目し、Direct3D の初期化、レンダリング、またはシャット ダウンについては説明しない。これらのタスクについては、「チュートリアル 1 : デバイスの作成」を参照すること。

このチュートリアルでは、カスタム頂点および頂点バッファを使ってジオメトリを表示する。カスタム頂点タイプの選択および頂点バッファの実装の詳細については、「チュートリアル 2 : 頂点のレンダリング」を参照すること。


ステップ 1 : ワールド トランスフォーム行列の定義

ワールド トランスフォーム行列は、3D モデル空間でジオメトリを平行移動、スケーリング、および回転する方法を定義する。

次のコードでは、三角形を y 軸上で回転させた後、Microsoft® Direct3D® デバイスに現在のワールド トランスフォームを設定している。

Dim matWorld As D3DMATRIX
D3DXMatrixRotationY matWorld, Timer * 4
g_D3DDevice.SetTransform D3DTS_WORLD, matWorld

最初のステップは、D3DXMatrixRotationY メソッドを呼び出して、Y 軸を中心に三角形を回転させることである。最初のパラメータは、返される行列を格納する D3DMATRIX 型である。2 番目のパラメータは、ラジアン単位の回転の角度である。

次のステップでは、Direct3DDevice8.SetTransform を呼び出して、現在のワールド トランスフォームを Direct3D デバイスに設定する。SetTransform で使用する最初のパラメータは、設定するトランスフォームを指定する。このサンプルでは、D3DTS_WORLD フラグを使用して、ワールド トランスフォームを指定する。2 番目のパラメータは、現在のトランスフォームとして設定する行列へのポインタである。

ワールド トランスフォームの詳細については、「ワールド トランスフォーム」を参照すること。

シーンのワールド トランスフォームを定義した後、ビュー トランスフォーム行列を準備できる。ここでも、トランスフォームを定義する順序は重要ではないことに注意すること。ただし、Direct3D では、(1) ワールド、(2) ビュー、(3) 射影の順序で、シーンに行列が適用される。

ビュー トランスフォーム行列の定義については、「ステップ 2 : ビュー トランスフォーム行列の定義」で説明する。


ステップ 2 : ビュー トランスフォーム行列の定義

ビュー トランスフォーム行列は、ビューの位置および回転を定義する。ビュー行列はシーンのカメラである。

次のコードでは、ビュー トランスフォーム行列を作成した後、Microsoft® Direct3D® デバイスに現在のビュー トランスフォームを設定している。

Dim matView As D3DMATRIX
D3DXMatrixLookAtLH matView, vec3(0#, 3#, -5#), _
                            vec3(0#, 0#,  0#), _
                            vec3(0#, 1#,  0#)

g_D3DDevice.SetTransform D3DTS_VIEW, matView

最初のステップは、D3DXMatrixLookAtLH を呼び出してビュー行列を定義することである。最初のパラメータは、返される行列を格納する D3DMATRIX 型である。第 2、第 3、第 4 のパラメータは、視点、注視点、および "上" 方向を定義する。ここでは、視点は z 軸方向に -5 単位、上方向に 3 単位の位置に、注視点は原点に、"上" 方向は y 軸方向に定義されている。

次のステップでは、Direct3DDevice8.SetTransform を呼び出して、現在のビュー トランスフォームを Direct3D デバイスに設定する。SetTransform で使用する最初のパラメータは、設定するトランスフォームを指定する。このサンプルでは、D3DTS_VIEW フラグを使用して、ビュー トランスフォームを指定する。2 番目のパラメータは、現在のトランスフォームとして設定する行列へのポインタである。

ビュー トランスフォームの詳細については、「ビュー トランスフォーム」を参照すること。

シーンのワールド トランスフォームを定義した後、射影トランスフォーム行列を準備できる。ここでも、トランスフォームを定義する順序は重要ではないことに注意すること。ただし、Direct3D では、(1) ワールド、(2) ビュー、(3) 射影の順序で、シーンに行列が適用される。

射影トランスフォーム行列の定義については、「ステップ 3 : 射影トランスフォーム行列の定義」で説明する。


ステップ 3 : 射影トランスフォーム行列の定義

射影トランスフォーム行列は、3D ビュー空間から 2D ビューポート空間にジオメトリをトランスフォームする方法を定義する。

次のコードでは、射影トランスフォーム行列を作成した後、Microsoft® Direct3D® デバイスにトランスフォームを適用している。

Dim matProj As D3DMATRIX
D3DXMatrixPerspectiveFovLH matProj, g_pi / 4, 1, 1, 1000
g_D3DDevice.SetTransform D3DTS_PROJECTION, matProj

最初のステップは、D3DXMatrixPerspectiveFovLH を呼び出して射影行列を設定することである。最初のパラメータは、返される行列を格納する D3DMATRIX 型である。2 番目のパラメータは視野を定義する。これによって、遠くにあるオブジェクトがどのように小さくなるかを指示する。標準的な視野は 1/4 pi であり、このサンプルでもこの値が使用されている。3 番目のパラメータはアスペクト比を定義する。サンプルで使用する標準のアスペクト比は 1 である。4 番目と 5 番目のパラメータは、近くのクリップ面と遠くのクリップ面を定義する。これは、ジオメトリがレンダリングされなくなる距離を決定する。Matrices サンプル プロジェクトでは、近くのクリップ面は 1 に、遠くのクリップ面は 100 に設定されている。

次のステップでは、Direct3DDevice8.SetTransform を呼び出して、現在の射影トランスフォームを Direct3D デバイスに設定する。SetTransform で使用する最初のパラメータは、設定するトランスフォームを指定する。このサンプルでは、D3DTS_PROJECTION フラグを使用して、射影トランスフォームを指定する。2 番目のパラメータは、現在のトランスフォームとして設定する行列へのポインタである。

射影トランスフォームの詳細については、「射影トランスフォーム」を参照すること。

このチュートリアルでは、行列の使い方を示した。「チュートリアル 4 : ライトの作成および使い方」では、シーンにライトを追加して、一層リアルにする方法を示す。


チュートリアル 4 : ライトの作成および使い方

Microsoft® Direct3D® ライトによって、3D オブジェクトは一層リアルになる。ライトを使用すると、シーン内の各ジオメトリ オブジェクトは、使用するライトの位置およびタイプに基づいてライトが当てられる。Lights サンプル プロジェクトでは、ライトおよびマテリアルについて説明する。

このチュートリアルでは、次のステップでマテリアルおよびライトを作成および使用する。

  • ステップ 1 : シーンのジオメトリの初期化
  • ステップ 2 : マテリアルおよびライトの設定

注 Lights サンプル プロジェクトのパスは次のとおりである。

(SDK ルート)\Samples\Multimedia\VBSamples\Direct3D\Tutorials\Tut04_Lights

Lights サンプル プロジェクトのコードは、Matrices サンプル プロジェクトのコードとほぼ同じである。このチュートリアルでは、ライトに固有のコードのみに注目し、Direct3D の初期化、レンダリング、またはシャット ダウンについては説明しない。これらのタスクについては、「チュートリアル 1 : デバイスの作成」を参照すること。

このチュートリアルでは、カスタム頂点および頂点バッファを使ってジオメトリを表示する。カスタム頂点タイプの選択および頂点バッファの実装の詳細については、「チュートリアル 2 : 頂点のレンダリング」を参照すること。

また、このチュートリアルでは、行列を利用してジオメトリをトランスフォームする。行列およびトランスフォームの詳細については、「チュートリアル 3 : 行列の使い方」を参照すること。


ステップ 1 : シーンのジオメトリの初期化

ライトを使用するための条件の 1 つは、各サーフェスが法線を持っていることである。これを処理するために、Lights サンプル プロジェクトでは別のカスタム頂点タイプを使用する。新しいカスタム頂点フォーマットには、3D 位置座標とサーフェスの法線が含まれる。サーフェスの法線は、Microsoft® Direct3D によって内部的にライティングの計算に使用される。

' カスタム頂点タイプの構造体。
Private Type CUSTOMVERTEX
    postion As D3DVECTOR    ' 頂点 3D 位置。
    normal As D3DVECTOR     ' 頂点のサーフェス法線。
End Type

' カスタム頂点構造体を記述するカスタム FVF。
Const D3DFVF_CUSTOMVERTEX = (D3DFVF_XYZ Or D3DFVF_NORMAL)

これで正しいベクトル フォーマットが定義されたので、Lights サンプル プロジェクトではアプリケーション定義関数 InitGeometry を呼び出して円柱を作成する。最初のステップは、頂点バッファに円柱のポイントを設定することである。次のコードでは、各ポイントが位置座標と法線によって定義されていることに注意すること。

For i = 0 To 49
    theta = (2 * g_pi * i) / (50 - 1)
    Vertices(2 * i + 0).postion = vec3(Sin(theta), -1, Cos(theta))
    Vertices(2 * i + 0).normal = vec3(Sin(theta), 0, Cos(theta))
    Vertices(2 * i + 1).postion = vec3(Sin(theta), 1, Cos(theta))
    Vertices(2 * i + 1).normal = vec3(Sin(theta), 0, Cos(theta))
Next

2 番目のステップは、次のコードのように、円柱のポイントを格納する頂点バッファを作成することである。

Set g_VB = g_D3DDevice.CreateVertexBuffer(VertexSizeInBytes * 50 * 2, _
                 0, D3DFVF_CUSTOMVERTEX, D3DPOOL_DEFAULT)
If g_VB Is Nothing Then Exit Function

頂点バッファに円柱の頂点を設定したら、頂点バッファをレンダリングすることができる。ただし、円柱をレンダリングする前に、このシーンのマテリアルとライトを設定する必要がある。これについては、「ステップ 2 : マテリアルおよびライトの設定」で説明する。


ステップ 2 : マテリアルおよびライトの設定

Microsoft® Direct3D® でライティングを使用するには、1 つまたは複数のライトを作成しなければならない。ジオメトリ オブジェクトが反射する色を決定するには、ジオメトリ オブジェクトのレンダリングに使用するマテリアルを作成する。Lights サンプル プロジェクトでは、シーンをレンダリングする前に、1 つのマテリアルと 1 つのディレクショナル ライトを設定する SetupLights というアプリケーション定義関数を呼び出す。この関数は、次のステップでマテリアルおよびライトを作成する。

  • ステップ 2.1 : マテリアルの作成
  • ステップ 2.2 : ライトの作成


ステップ 2.1 : マテリアルの作成

マテリアルは、ジオメトリ オブジェクトにライトが当たったときに、ジオメトリ オブジェクトのサーフェスから反射される色を定義する。次のコードでは、D3DMATERIAL8 構造体を使って、黄色のマテリアルを作成している。

Dim mtrl As D3DMATERIAL8
With col:    .r = 1: .g = 1: .b = 0: .a = 1:   End With
mtrl.diffuse = col
mtrl.Ambient = col
g_D3DDevice.SetMaterial mtrl

このマテリアルのディフューズ色およびアンビエント色は黄色に設定される。Direct3DDevice8.SetMaterial メソッドの呼び出しによって、シーンのレンダリングに使用される Microsoft® Direct3D® デバイスにマテリアルが適用される。SetMaterial が受け取るパラメータは、設定するマテリアルのアドレスだけである。この呼び出しが行われた後、別のマテリアルを指定する SetMaterial の次の呼び出しが行われるまで、このマテリアルを使って各プリミティブがレンダリングされる。

これでシーンにマテリアルが適用されたので、次のステップはライトを作成することである。これについては、「ステップ 2.2 : ライトの作成」で説明する。


ステップ 2.2 : ライトの作成

Microsoft® Direct3D® では、3 種類のライトを使用できる。ポイント ライト、ディレクショナル ライト、およびスポット ライトである。Lights サンプル プロジェクトでは、光が 1 方向に進むディレクショナル ライトを作成し、ライトの方向を変化させている。

次のコードでは、D3DLIGHT8 構造体を使って、ディレクショナル ライトを定義する。

Dim light As D3DLIGHT8
light.Type = D3DLIGHT_DIRECTIONAL

次のコードでは、このライトのディフューズ色を白に設定している。

light.diffuse.r = 1#
light.diffuse.g = 1#
light.diffuse.b = 1#

次のコードでは、ライトの方向を円形に回転させている。

light.Direction.x = Cos(Timer * 2)
light.Direction.y = 1#
light.Direction.z = Sin(Timer * 2)

範囲を指定して、ライトのエフェクトが届く範囲を Direct3D に指示できる。このメンバは、ディレクショナル ライトには影響しない。次のコードでは、このライトに 1000 単位の範囲を割り当てている。

light.Range = 1000#

次のコードでは、Direct3DDevice8.SetLight を呼び出して、Direct3D デバイスにライトを割り当てている。

g_D3DDevice.SetLight 0, light     ' D3D にライトの情報を設定する。

SetLight が受け取る最初のパラメータは、このライトが割り当てられるインデックスである。ライトが既にその位置に存在する場合、新しいライトによって上書きされることに注意すること。2 番目のパラメータは、ライトを定義する light 構造体へのポインタである。Lights サンプル プロジェクトでは、このライトをインデックス 0 に配置する。

次のコードは、Direct3DDevice8.LightEnable を呼び出してライトを有効にする。

g_D3DDevice.LightEnable 0, 1

LightEnable が受け取る最初のパラメータは、有効にするライトのインデックスである。2 番目のパラメータは、ライトをオンにする (1) か、オフにする (0) かを指定する値である。Lights サンプル プロジェクトでは、インデックス 0 にあるライトがオンになっている。

このサンプルの次のステップは、Direct3DDevice8.SetRenderState を呼び出して、アンビエント ライトをオンにすることである。

g_D3DDevice.SetRenderState D3DRS_AMBIENT, &H202020

SetRenderState が受け取る 2 つのパラメータは、変更するデバイス ステート変数と、その変数に設定する値である。このサンプルでは、D3DRS_AMBIENT デバイス変数をライト グレー (&H202020) に設定している。アンビエント ライトは、すべてのオブジェクトを指定された色でライトアップする。

Direct3D でライトを使用するには、有効にしなければならない。次のコードでは、SetRenderState を呼び出して、ライトをレンダリングするように Direct3D に指示している。

g_D3DDevice.SetRenderState D3DRS_LIGHTING, 1    ' ライティングを確実に有効にする。

このサンプルでは、D3DRS_LIGHTING デバイス変数を TRUE に設定している。これは、ライトのレンダリングを有効にする効果がある。

ライティングの詳細については、「Direct3D のライティングにおける数学的計算」を参照すること。

このチュートリアルでは、ライトとマテリアルの使い方を示した。「チュートリアル 5 : テクスチャ マップの使い方」では、サーフェスにテクスチャを追加する方法を示す。


チュートリアル 5 : テクスチャ マップの使い方

ライトとマテリアルによって、シーンは一層リアルになるが、最もリアルさが増すのはサーフェスにテクスチャを追加したときである。テクスチャは、サーフェスに縮小ラップされた壁紙であると考えることができる。たとえば、木のテクスチャを立方体に貼り付けることによって、その立方体が木でできているように見せることができる。Texture サンプル プロジェクトでは、Lights サンプルで作成した円柱にバナナの皮のテクスチャを追加する。このチュートリアルでは、テクスチャのロード、頂点の設定、およびテクスチャを使ったオブジェクトの表示の方法を説明する。

このチュートリアルでは、次のステップでテクスチャを実装する。

  • ステップ 1 : カスタム ベクトル フォーマットの定義
  • ステップ 2 : 画面のジオメトリの初期化
  • ステップ 3 : シーンのレンダリング

注 Textures サンプル プロジェクトのパスは次のとおりである。

(SDK ルート)\Samples\Multimedia\VBSamples\Direct3D\Tutorials\Tut05_Textures

Texture サンプル プロジェクトのコードは、Lights サンプル プロジェクトのコードとほぼ同じである。ただし、Texture サンプル プロジェクトではマテリアルやライトを作成しないポイントが異なる。このチュートリアルでは、テクスチャに固有のコードのみに注目し、Microsoft® Direct3D® の初期化、レンダリング、またはシャット ダウンについては説明しない。これらのタスクについては、「チュートリアル 1 : デバイスの作成」を参照すること。

このチュートリアルでは、カスタム頂点および頂点バッファを使ってジオメトリを表示する。カスタム頂点タイプの選択および頂点バッファの実装の詳細については、「チュートリアル 2 : 頂点のレンダリング」を参照すること。

また、このチュートリアルでは、行列を利用してジオメトリをトランスフォームする。行列およびトランスフォームの詳細については、「チュートリアル 3 : 行列の使い方」を参照すること。


ステップ 1 : カスタム ベクトル フォーマットの定義

テクスチャを使用するには、テクスチャ座標を含むカスタム頂点フォーマットを定義しなければならない。テクスチャ座標によって、プリミティブ内の各ベクトルについてテクスチャを配置する場所を Microsoft® Direct3D® に指示する。テクスチャ座標の範囲は 0.0 から 1.0 までで、(0.0, 0.0) はテクスチャの左上を表し、(1.0, 1.0) はテクスチャの右下を表す。

次のコードは、Texture サンプル プロジェクトで、テクスチャ座標を含む、カスタム頂点フォーマットを設定する方法を示している。

' カスタム頂点タイプ。
Private Type CUSTOMVERTEX
    postion As D3DVECTOR    ' 頂点の 3D 位置。
    color As Long           ' 頂点の色。
    tu As Single            ' テクスチャ マップ座標。
    tv As Single            ' テクスチャ マップ座標。
End Type

' カスタム FVF。
Const D3DFVF_CUSTOMVERTEX = (D3DFVF_XYZ Or D3DFVF_DIFFUSE Or D3DFVF_TEX1)

テクスチャ座標の詳細については、「テクスチャ座標」を参照すること。

カスタム頂点タイプが定義されたので、次のステップでは、テクスチャをロードして円柱を作成する。これについては、「ステップ 2 : 画面のジオメトリの初期化」で説明する。


ステップ 2 : 画面のジオメトリの初期化

レンダリングを行う前に、Texture サンプル プロジェクトでは、アプリケーション定義関数 InitGeometry を呼び出して、テクスチャを作成し、円柱のジオメトリを設定している。

テクスチャはファイル ベースのイメージから作成される。次のコードでは、D3DX8.CreateTextureFromFile を使って、Banana.bmp から円柱のサーフェスを覆うためのテクスチャを作成している。

Set g_Texture = g_D3DX.CreateTextureFromFile(g_D3DDevice, App.Path + "\banana.bmp")
If g_Texture Is Nothing Then Exit Function

CreateTextureFromFile が受け取る最初のパラメータは、テクスチャをレンダリングするために使用される Microsoft® Direct3D® デバイスである。2 番目のパラメータは、作成するテクスチャの元のファイル名を指定する ANSI 文字列である。このサンプルでは、Banana.bmp を指定して、このファイルからイメージをロードする。

バナナのテクスチャがロードされ、使用可能になる。次のステップは円柱を作成することである。次のコードでは、頂点バッファに円柱のデータを設定している。各点はテクスチャ座標 (tu, tv) を持つことに注意すること。

For i = 0 To 49
    theta = (2 * g_pi * i) / (50 - 1)

    Vertices(2 * i + 0).position = vec3(Sin(theta), -1, Cos(theta))
    Vertices(2 * i + 0).color = &HFFFFFFFF  ' 白。
    Vertices(2 * i + 0).tu = i / (50 - 1)
    Vertices(2 * i + 0).tv = 1

    Vertices(2 * i + 1).position = vec3(Sin(theta), 1, Cos(theta))
    Vertices(2 * i + 1).color = &HFF808080  ' グレー。
    Vertices(2 * i + 1).tu = i / (50 - 1)
    Vertices(2 * i + 1).tv = 0
Next

各頂点には、位置座標、色、およびテクスチャ座標が含まれる。Texture サンプル プロジェクトでは、テクスチャが円柱の周囲をなめらかに覆うように、各点のテクスチャ座標を設定している。

テクスチャがロードされ、頂点バッファをレンダリングする準備ができたので、次はディスプレイをレンダリングする。これについては、「ステップ 3 : シーンのレンダリング」で説明する。


ステップ 3 : シーンのレンダリング

ジオメトリが初期化されたら、シーンをレンダリングする。テクスチャを持つオブジェクトをレンダリングするには、そのテクスチャが現在のテクスチャの 1 つとして設定されていなければならない。次のステップは、テクスチャ ステージ ステートの値を設定することである。テクスチャ ステージ ステートによって、テクスチャをレンダリングする動作を定義できる。たとえば、複数のテクスチャを 1 つにブレンディングすることができる。

Texture サンプル プロジェクトでは、まず、使用するテクスチャを設定する。次のコードでは、Direct3DDevice8.SetTexture を使って、Microsoft® Direct3D® デバイスがレンダリングするテクスチャを設定している。

g_D3DDevice.SetTexture 0, g_Texture

SetTexture が受け取る最初のパラメータは、テクスチャを設定するステージ識別子である。1 つのデバイスで最大 8 つのテクスチャを持つため、最大値は 7 である。このサンプルでは 1 つだけテクスチャがあり、ステージ 0 に配置している。2 番目のパラメータは、テクスチャ オブジェクトへのポインタである。このサンプルでは、アプリケーション定義関数 InitGeometry で作成したテクスチャ オブジェクトを使用する。

次のコードは、Direct3DDevice8.SetTextureStageState メソッドを呼び出して、テクスチャ ステージ ステートの値を設定する。

g_D3DDevice.SetTextureStageState 0, D3DTSS_COLOROP, D3DTOP_MODULATE
g_D3DDevice.SetTextureStageState 0, D3DTSS_COLORARG1, D3DTA_TEXTURE
g_D3DDevice.SetTextureStageState 0, D3DTSS_COLORARG2, D3DTA_DIFFUSE
g_D3DDevice.SetTextureStageState 0, D3DTSS_ALPHAOP, D3DTOP_DISABLE

SetTextureState が受け取る最初のパラメータは、設定するステート変数のステージ インデックスである。このサンプルでは、ステージ 0 のテクスチャの値を変更するので、ここでは 0 を指定している。次のパラメータは、設定するテクスチャ ステートである。有効なすべてのテクスチャ ステートおよびその意味の一覧については、「CONST_D3DTEXTURESTAGESTATETYPE」を参照すること。次のパラメータは、テクスチャ ステートに設定する値である。ここに指定する値は、変更するテクスチャ ステージ ステートの値に基づいている。

各テクスチャ ステージ ステートに適切な値を設定すると、円柱をレンダリングすることができ、テクスチャがサーフェスに追加される。

テクスチャ座標のもう 1 つの使い方は、自動的にテクスチャ座標を生成する方法である。この方法では、テクスチャ座標インデックス (TCI) を使用する。TCI では、テクスチャ行列を使って、(x,y,z) TCI 座標を (tu, tv) テクスチャ座標にトランスフォームする。Texture サンプル プロジェクトでは、カメラ空間での頂点の位置座標を使って、テクスチャ座標を生成している。

最初のステップは、トランスフォームに使用する行列を作成することである。行列を作成するコードを以下に示す。

Dim mat As D3DMATRIX

mat.m11 = 0.25: mat.m12 = 0#:     mat.m13 = 0#: mat.m14 = 0#
mat.m21 = 0#:   mat.m22 = -0.25:  mat.m23 = 0#: mat.m24 = 0#
mat.m31 = 0#:   mat.m32 = 0#:     mat.m33 = 1#: mat.m34 = 0#
mat.m41 = 0.5:  mat.m42 = 0.5:    mat.m43 = 0#: mat.m44 = 1#

行列を作成したら、次のコードのように、SetTransform を呼び出して設定しなければならない。

g_D3DDevice.SetTransform D3DTS_TEXTURE0, mat

D3DTS_TEXTURE0 フラグは、テクスチャ ステージ 0 のテクスチャにトランスフォームを適用するよう Direct3D に指示する。このサンプルの次のステップでは、希望どおりの効果を出すために、さらにテクスチャ ステージ ステート値を設定する。この処理は、次のコードで行われる。

g_D3DDevice.SetTextureStageState 0, D3DTSS_TEXTURETRANSFORMFLAGS, D3DTTFF_COUNT2
g_D3DDevice.SetTextureStageState 0, D3DTSS_TEXCOORDINDEX, D3DTSS_TCI_CAMERASPACEPOSITION

テクスチャ座標が設定されたので、シーンをレンダリングすることができる。円柱の座標は自動的に作成されることに注意すること。この設定では、ジオメトリ形状がレンダリングされた後、レンダリング画面にテクスチャを重ねるエフェクトが適用される。

テクスチャの詳細については、「テクスチャ」を参照すること。

このチュートリアルでは、サーフェスのテクスチャの使い方を示した。「チュートリアル 6 : メッシュの使い方」では、メッシュを含む複雑なジオメトリ形状の使用方法を示す。


チュートリアル 6 : メッシュの使い方

複雑なジオメトリは通常 3D モデリング ソフトウェアを使ってモデリングされ、ファイルに保存される。たとえば、.x ファイル フォーマットなどがある。Microsoft® Direct3D® では、メッシュを使ってこれらのファイルからオブジェクトをロードする。メッシュは少し複雑であるが、D3DX には便利な関数が含まれている。Meshes サンプル プロジェクトでは、メッシュに関するトピックを説明し、メッシュのロード、レンダリング、アンロードの方法を示す。

このチュートリアルでは、次のステップで、メッシュをロードおよびレンダリングする方法を示す。

  • ステップ 1 : メッシュ オブジェクトのロード
  • ステップ 2 : メッシュ オブジェクトのレンダリング

Meshes サンプル プロジェクトのパスは次のとおりである。

(SDK ルート)\Samples\Multimedia\VBSamples\Direct3D\Tutorials\Tut06_Meshes

Meshes サンプル プロジェクトのコードは、Lights サンプル プロジェクトのコードとほぼ同じである。ただし、Meshes サンプル プロジェクトではマテリアルやライトを作成しないポイントが異なる。このチュートリアルでは、メッシュに固有のコードのみに注目し、Direct3D の初期化、レンダリング、またはシャット ダウンについては説明しない。これらのタスクについては、「チュートリアル 1 : デバイスの作成」を参照すること。

このチュートリアルでは、カスタム頂点および頂点バッファを使ってジオメトリを表示する。カスタム頂点タイプの選択および頂点バッファの実装の詳細については、「チュートリアル 2 : 頂点のレンダリング」を参照すること。

また、このチュートリアルでは、行列を利用してジオメトリをトランスフォームする。行列およびトランスフォームの詳細については、「チュートリアル 3 : 行列の使い方」を参照すること。

また、このチュートリアルでは、テクスチャを使ってメッシュのサーフェスを覆う。テクスチャのロードおよび使用の詳細については、「チュートリアル 5 : テクスチャ マップの使い方」を参照すること。


ステップ 1 : メッシュ オブジェクトのロード

Microsoft® Direct3D® アプリケーションでメッシュを使用するには、まずメッシュをロードしなければならない。Meshes サンプル プロジェクトでは、必要な Direct3D オブジェクトをロードした後、アプリケーション定義関数 InitGeometry を呼び出して、トラのメッシュをロードする。

メッシュには、使用するすべてのマテリアルおよびテクスチャに関する情報を格納するマテリアル バッファが必要である。この関数は、最初にマテリアル バッファを宣言する。

Dim MtrlBuffer As D3DXBuffer

Meshes サンプル プロジェクトでは、次のコードに示すように、D3DX8.LoadMeshFromX メソッドを使ってメッシュをロードする。

Set g_Mesh = g_D3DX.LoadMeshFromX(App.Path + "\Tiger.x", D3DXMESH_MANAGED, _
                               g_D3DDevice, Nothing, MtrlBuffer, g_NumMaterials)

If g_Mesh Is Nothing Then Exit Function

D3DXLoadMeshFromX が受け取る最初のパラメータは、ロードする Microsoft DirectX® ファイルの名前を指示する文字列である。このサンプルでは、Tiger.x からトラのメッシュをロードする。2 番目のパラメータは、メッシュの作成方法を Direct3D に指示する。このサンプルでは D3DXMESH_MANAGED フラグを使用している。このフラグは、インデックス バッファ用に D3DPOOL_MANAGED メモリ クラスを使用するように Direct3D に指示する。3 番目のパラメータは、メッシュのレンダリングに使用する Direct3D デバイスである。4 番目のパラメータは、D3DXBuffer オブジェクトを取る。このオブジェクトには、各面の隣接する面に関する情報が格納される。このサンプルでは、この情報は必要ないので、このパラメータは Nothing に設定されている。5 番目のパラメータも ID3DXBuffer オブジェクトへのポインタを取る。このメソッドが終了した後、このオブジェクトにはメッシュの D3DXMATERIAL 構造体が格納される。6 番目のパラメータは、このメソッドが返った後、RetMaterials パラメータに配置される D3DXMATERIAL 構造体の数を指定する Long 型の変数である。

メッシュ オブジェクトおよびマテリアルの情報がロードされた後、マテリアル バッファからマテリアルのプロパティおよびテクスチャ名を抽出する必要がある。

この情報をマテリアル バッファから取得する前に、このメッシュのすべてのマテリアルおよびテクスチャを格納できるように、マテリアルおよびテクスチャの配列のサイズを変更しなければならない。

ReDim g_MeshMaterials(g_NumMaterials)
ReDim g_MeshTextures(g_NumMaterials)

メッシュ内の各マテリアルについて、次の処理が行われる。

最初のステップは、次のコードに示されているように、D3DX8.BufferGetMaterial を使ってマテリアルをコピーすることである。

g_D3DX.BufferGetMaterial MtrlBuffer, i, g_MeshMaterials(i)

BufferGetMaterial が受け取る最初のパラメータはマテリアル オブジェクトで、この場合は、MtrlBuffer である。2 番目のパラメータは、取得するマテリアルのインデックスである。3 番目のパラメータは、マテリアルを配置する位置である。

第 2 のステップは、次のコードに示されているように、マテリアルのアンビエント色を設定することである。

g_MeshMaterials(i).Ambient = g_MeshMaterials(i).diffuse

最後のステップは、次のコードに示されているように、マテリアルのテクスチャを作成することである。

strTexName = g_D3DX.BufferGetTextureName(MtrlBuffer, i)
If strTexName <> "" Then
    Set g_MeshTextures(i) = g_D3DX.CreateTextureFromFile(g_D3DDevice, App.Path + "\" + strTexName)
End If

すべてのマテリアルをロードした後、マテリアル バッファを Nothing に設定して、マテリアル バッファの使用を終了したことを Direct3D に知らせる必要がある。

Set MtrlBuffer = Nothing

メッシュ、および対応するマテリアルとテクスチャがロードされる。これでメッシュをディスプレイにレンダリングできる。これについては、「ステップ 2 : メッシュ オブジェクトのレンダリング」で説明する。


ステップ 2 : メッシュ オブジェクトのレンダリング

メッシュがロードされ、レンダリングの準備ができている。メッシュは、メッシュについてロードされた各マテリアルのサブセットに分割される。各サブセットをレンダリングするために、メッシュはループでレンダリングされる。ループの最初のステップは、次のコードに示されているように、サブセットのマテリアルを設定することである。

g_D3DDevice.SetMaterial g_MeshMaterials(i)

ループの 2 番目のステップは、次のコードに示されているように、サブセットのテクスチャを設定することである。

g_D3DDevice.SetTexture 0, g_MeshTextures(i)

マテリアルとテクスチャを設定した後、次のコードに示されているように、D3DXBaseMesh.DrawSubset メソッドを使ってサブセットが描画される。

g_Mesh.DrawSubset i

DrawSubset メソッドは、描画するメッシュのサブセットを指定する Long 型の値を取る。このサンプルでは、ループを実行するたびにインクリメントされる値を使用する。

このループは、メッシュ内の各サブセットがレンダリングされるまで実行される。

このチュートリアルでは、メッシュのロードとレンダリングの方法を示した。このセクションのチュートリアルはこれで終わりである。Microsoft Visual Basic® での標準的な Microsoft® Direct3D® アプリケーションの作成方法については、「DirectX Graphics Visual Basic サンプル」を参照すること。


DirectX Graphics Visual Basic サンプル

次のサンプル アプリケーションには、Microsoft® Direct3D® および Direct3DX アプリケーション プログラミング インターフェイスの使い方と機能が示されている。

  • AnimKeys サンプル
  • AutoParts サンプル
  • BarGraph サンプル
  • Billboard サンプル
  • Dolphin サンプル
  • Donuts サンプル
  • DXTex ツール
  • PixelShader サンプル
  • PointSprites サンプル
  • ScatterGraph サンプル
  • SkinnedMesh サンプル
  • VertexBlend サンプル
  • VertexShader サンプル

参照

DirectX Graphics Visual Basic チュートリアル


AnimKeys サンプル

説明

AnimKeys サンプルでは、Microsoft® Direct3D® フレームワークを使用して、.x ファイルを持つキーフレーム アニメーションをロードおよび再生する方法を示す。アニメーション情報は .x ファイルに含まれている。

パス

ソース :(SDK ルート)\Samples\Multimedia\VBSamples\Direct3D\AnimKeys

実行可能ファイル :(SDK ルート)\Samples\Multimedia\VBSamples\Direct3D\Bin

ユーザーズ ガイド

次の表は実装されているキーを示している。

キー | 動作
F2 | 新しいレンダリング デバイスまたはディスプレイ モードの選択を求めるメッセージを表示する。
Alt + Enter | フルスクリーン モードとウィンドウ モードを切り替える。
Esc | アプリケーションを終了する。

プログラミング上の注意

D3DUtil_LoadFromFile に渡される最後の引数は、.x ファイル内のすべてのアニメーションの親となる CD3DAnimation クラスである。その後、Animation.SetTime を使用してモデルを配置することができる。

このサンプルでは、ヘルパー関数などのプログラミング要素から構成される Microsoft DirectX® コードを使用する。このコードは、DirectX SDK のほかのサンプルと共有されている。共通のソース コードは、(SDK ルート)\Samples\Multimedia\VBSamples\Common にある。


AutoParts サンプル

説明

AutoParts サンプルでは、3D データベースに対してピッキングを使用する方法を示す。

パス

ソース :(SDK ルート)\Samples\Multimedia\VBSamples\Direct3D\Autoparts

実行可能ファイル :(SDK ルート)\Samples\Multimedia\VBSamples\Direct3D\Bin

ユーザーズ ガイド

左側のツリー ビューで [Click here] を選択して、エンジン モデルをロードする。マウス ボタンを押さえてドラッグすることでモデルを回転できる。任意の箇所をクリックすると、それに関する説明が左下隅に表示される。

[Add and Remove from Invoice] ボタンはインボイス リストを管理するが、[Order] ボタンは何も機能しない。

プログラミング上の注意

エンジン モデルの各オブジェクトには名前が付けられる。これらの名前は一意であり、データベースの相互参照に使用できる。この例では、カスタム テキスト データベースを使用して、MDAC のインストールが要求されないようにする。そのデータベースからは、価格やパーツ番号など、パーツについての詳細情報が収集される。

このサンプルでは、ヘルパー関数などのプログラミング要素から構成される Microsoft® DirectX® コードを使用する。このコードは、DirectX SDK のほかのサンプルと共有されている。共通のソース コードは、(SDK ルート)\Samples\Multimedia\VBSamples\Common にある。


BarGraph サンプル

説明

BarGraph サンプルでは、Microsoft® Direct3D® をグラフ表示に使用する方法について説明する。ここでは、D3DX フレームワークの RenderToSurface 機能を使用して、テキストとビットマップを動的にレンダリングする。

パス

ソース :(SDK ルート)\Samples\Multimedia\VBSamples\Direct3D\AnimKeys

実行可能ファイル :(SDK ルート)\Samples\Multimedia\VBSamples\Direct3D\Bin

ユーザーズ ガイド

サンプル ウィンドウで右クリックして、ショートカット メニューを表示する。このメニューを使用して、.csv (カンマ区切り) ファイルから新しいデータをロードできる。.csv ファイルは、Microsoft Excel またはその他のスプレッドシート プログラムからエクスポートすることができる。

このファイルは、先頭の行および列が、データにタイトル付けするヘッダーとなるようにフォーマットする必要がある。ヘッダーには、この部分にピクチャが含まれていることを示すタグ TEXTURE:filename.bmp を指定できる。残りのデータ部は数値でなければならない。例については、(SDK ルート)\Samples\Multimedia\VBSamples\Media の Bargraphdata.csv を参照すること。

マウス ボタンを押さえてドラッグすると、グラフが回転する。

次の表は実装されているキーを示している。

キー | 動作
→ | カメラを右に移動する。
← | カメラを左に移動する。
↑ | カメラを上に移動する。
↓ | カメラを下に移動する。
W | カメラを前方に移動する。
S | カメラを後方に移動する。
E | カメラを右に回転する。
Q | カメラを左に回転する。
A | カメラを上に回転する。
Z | カメラを下に回転する。

プログラミング上の注意

このサンプルでは、ヘルパー関数などのプログラミング要素から構成される Microsoft DirectX® コードを使用する。このコードは、DirectX SDK のほかのサンプルと共有されている。共通のソース コードは、(SDK ルート)\Samples\Multimedia\VBSamples\Common にある。


Billboard サンプル

説明

Billboard サンプルでは、ビルボーディングの手法を示している。複雑な 3D モデル (ポリゴン数の多い木のモデルなど) をレンダリングする代わりに、モデルの 2D イメージをレンダリングし、常に視点に向くように回転させる。この手法は、木、雲、煙、爆発などをレンダリングするために、一般的に使用される。詳細については、「ビルボーディング」を参照すること。

Billboard サンプルでは、カメラは木で覆われた丘の 3D シーンを飛行する。これらの木は 3D オブジェクトのように見えるが、実際は 2D ビルボード化されたイメージであり、視点に向かって回転する。丘の地形およびスカイボックス (空のテクスチャを含む立方体) は、.x ファイルからロードされるオブジェクトである。これらは視覚効果のために使用され、ビルボーディング手法とは無関係である。

パス

ソース :(SDK ルート)\Samples\Multimedia\VBSamples\Direct3D\Billboard

実行可能ファイル :(SDK ルート)\Samples\Multimedia\VBSamples\Direct3D\Bin

ユーザーズ ガイド

次の表は実装されているキーを示している。

キー | 動作
F2 | 新しいレンダリング デバイスまたはディスプレイ モードの選択を求めるメッセージを表示する。
Alt + Enter | フルスクリーン モードとウィンドウ モードを切り替える。
Esc | アプリケーションを終了する。

プログラミング上の注意

このサンプルでは、ビルボーディング手法に重点を置いている。カメラは各フレームで移動するので、それに従って視点も変化する。視点が変化すると、ビルボードが新しい視点の方を向くように、y 軸に沿ってビルボードを回転させる回転行列が生成される。ビルボード行列の計算は FrameMove 関数で行われる。通常ビルボードには透明なピクセルが含まれているので、必要に応じて適切なアルファ ブレンディングを行うために、木もこの関数によって分類される。木は、DrawTrees 関数によって頂点バッファからレンダリングされる。

このサンプルのビルボードは、y 軸に沿ってのみ回転するように制限されている。このようにしないと、木の幹が地面に固定されているように見えない。3D フライト シミュレータやスペース シューティング ゲームの爆発などの効果では、ビルボードは通常 1 つの軸に制約されない。

このサンプルでは、ヘルパー関数などのプログラミング要素から構成される Microsoft DirectX® コードを使用する。このコードは、DirectX SDK のほかのサンプルと共有されている。共通のソース コードは、(SDK ルート)\Samples\Multimedia\VBSamples\Common にある。


Dolphin サンプル

説明

Dolphin サンプルでは、イルカと海底にコースティック エフェクトを適用した、イルカが泳ぐ水中のシーンを示す。イルカはトゥイーニングと呼ばれる手法を使ってアニメーションされる。水中のエフェクトにはフォグを使用し、ウォーター コースティクスにはアニメーションしたテクスチャのセットを使用している。

パス

ソース :(SDK ルート)\Samples\Multimedia\VBSamples\Direct3D\Dolphin

実行可能ファイル :(SDK ルート)\Samples\Multimedia\VBSamples\Direct3D\Bin

ユーザーズ ガイド

次の表は実装されているキーを示している。

キー | 動作
F2 | 新しいレンダリング デバイスまたはディスプレイ モードの選択を求めるメッセージを表示する。
Alt + Enter | フルスクリーン モードとウィンドウ モードを切り替える。
Esc | アプリケーションを終了する。

プログラミング上の注意

このサンプルでは、複数の処理が行われている。まず、フォグを使用して海中の様子を表現する。フォグ パラメータは、InitDeviceObjects 関数に設定される。

ウォーター コースティクスは、32 種類のテクスチャのセット (Caust00.tga ～ Caust31.tga) をアニメーションすることによって実現される。このコースティクスは、マルチテクスチャまたはマルチパス ブレンディング手法を使ってシーンにブレンディングできる。イルカの下側にはコースティック エフェクトを適用しない方がよいので、別のパスでアンビエント ライトを削除し、イルカを上から照らすようにした後、ディフューズ色がコースティック テクスチャにブレンドされている。

トゥイーニングを使用することで、イルカ モデルの頂点は、頂点の複数のセットから線形ブレンディングされている。ほかの頂点のセットのソース モデルは、3 つの位置のイルカのモデルで構成される Dolphin_group.x からロードされる。各フレームについて、これらのメッシュの位置と法線の組み合わせをブレンディングすることによって、最終出力のメッシュが生成される。

トゥイーニングの詳細については、「頂点トゥイーニング」を参照すること。

このサンプルでは、ヘルパー関数などのプログラミング要素から構成される Microsoft® DirectX® コードを使用する。このコードは、DirectX SDK のほかのサンプルと共有されている。共通のソース コードは、(SDK ルート)\Samples\Multimedia\VBSamples\Common にある。


Donuts サンプル

説明

Donuts サンプルでは、Microsoft® Direct3D® を使用して、2 次元スプライト エンジンを作成する方法を示す。

パス

ソース :(SDK ルート)\Samples\Multimedia\VBSamples\Direct3D\Donuts

実行可能ファイル :(SDK ルート)\Samples\Multimedia\VBSamples\Direct3D\Bin

ユーザーズ ガイド

次の表は実装されているキーを示している。

キー | 動作
Alt + Enter | フルスクリーン モードとウィンドウ モードを切り替える。
Esc | アプリケーションを終了する。

プログラミング上の注意

バックグラウンドは、2 つの TLVertex (スクリーン空間) 三角形を使用してレンダリングされる。スプライトは、スプライトのプロパティ (位置、方向、速度、サイズなど) を格納するユーザー定義型の配列として定義される。各スプライトは、それぞれのフレームで 2 つの TLVertex 三角形としてレンダリングされる。

このサンプルでは、ヘルパー関数などのプログラミング要素から構成される Microsoft DirectX® コードを使用する。このコードは、DirectX SDK のほかのサンプルと共有されている。共通のソース コードは、(SDK ルート)\Samples\Multimedia\VBSamples\Common にある。


DXTex ツール

説明

DXTex ツールでは、新しい DXTn 圧縮フォーマットを使用したテクスチャ マップを作成できる。DXTn 圧縮されたテクスチャの作成は難しいことではない。ただし、Microsoft® Direct3D® では、Direct3DTexture8 オブジェクトを使用して自動的に変換できる。上級の開発者であれば特定のニーズを満たすツールを作成することもできるが、DXTex ツールは便利で基本的な機能を備えている。

機能

  • .bmp および DirectDrawSurface (DDS) ファイルを開く。詳細については、後の「DDS ファイル フォーマット」を参照すること。
  • .bmp ファイルをアルファ チャネルとして明示的または非明示的に開く。このとき、<filename>_a.bmp 命名規則を使用する。
  • テクスチャを DDS フォーマットで保存する。
  • 5 種類の DXTn 圧縮フォーマットに変換する。
  • ボックス フィルタを使用してミップマップを生成する。
  • アルファ チャネルをグレースケール イメージとして、またはユーザー選択可能なバックグラウンド カラーを使用して表示する。
  • 異なるフォーマット間での画質の比較を画面上で簡単に行える。

パス

ソース :(SDK ルート)\Samples\Multimedia\Direct3D\DXTex

実行可能ファイル :(SDK Root)\Bin\DXUtils

ユーザー インターフェイス

DxTex では、各テクスチャ マップはドキュメントであり、同時に複数のドキュメントを開くことができる、従来のユーザー インターフェイス (UI) を使用している。ただし、DxTex でドキュメントを開いているときは、各ドキュメントでは 1 つまたは 2 つのフォーマットでテクスチャを使用できる。たとえば、.bmp ファイルをインポートすることができる。これによって、自動的に 32 ビット ARGB テクスチャが作成される。次に、このテクスチャを DXT1 フォーマットに変換できる。この時点でドキュメントでは 2 つのフォーマットでイメージが開いており、ウィンドウをクリックするか、[View] メニューの [Original View] または [New View] をクリックして、これらのフォーマットを切り替えることができる。このように操作することで、イメージ圧縮によって生じる不自然な効果を確認でき、イメージの品質を段階的に劣化させることなく別の圧縮フォーマットを簡単に試すことができる。たとえば、この方法を使用せずに、イメージを ARGB から DXT1 に変換すると、アルファの 1 ビットを除くすべてのビットが失われる。

その後 DXT2 に変換しても、アルファ レベルは 2 つしか存在しないことになる。DxTex システムでは、この 2 回目の変換は元の ARGB フォーマットから行われ、変換後の DXT2 イメージには、DXT2 がサポートする 16 レベルのアルファがすべて含まれる。このイメージを保存すると、元のフォーマットは破棄されて新しいフォーマットのみが保存される。

DxTex インターフェイスを使用するときには、次の点に注意すること。

  • ドキュメントが開かれて以降、フォーマット変換が要求されていない場合、その 1 つのフォーマットが元のフォーマットとなり、ドキュメントを保存するときにはそのフォーマットでイメージが書き込まれる。
  • ドキュメントが開かれて以降、フォーマット変換が要求された場合、変換後のフォーマットが新しいフォーマットとなり、ドキュメントを保存するときにはそのフォーマットでイメージが書き込まれる。
  • 2 回目のフォーマット変換が要求された場合、最初の変換で作成されたフォーマットが 2 つ目のフォーマットに置き換えられる。元のフォーマットは変更されない。
  • ミップマップの生成は、両方のフォーマットに同時に適用される。
  • 元のフォーマットに複数のミップマップがあり、新しいフォーマットへの変換が要求された場合、新しいフォーマットにも自動的に複数のミップマップが存在することになる。

パフォーマンス

DxTex では、3D ハードウェアが使用可能かどうかに関係なく、Microsoft Direct3D リファレンス ラスタライザを使ってテクスチャを描画する。したがって、大きなテクスチャ (256x256 ピクセルを超える) の場合、プログラムは CPU の速度に応じていくらか遅くなることがある。

DSS ファイル フォーマット

DxTex ネイティブ ファイル フォーマットは、DirectDrawSurface に情報をカプセル化するため、DDS ファイル フォーマットと呼ばれる。フォーマットは、次のとおりである。

Magic As Long '0x20534444, または "DDS"
ddsd As DDSURFACEDESC2    ' サーフェスのフォーマットについての
                          ' 情報を提供する。
Data1 As Any              ' メイン サーフェスに関するサーフェス データを格納する
                          ' 配列の最初の要素。
[Data2 As Any...]' アタッチされたサーフェスに関するサーフェス データを格納する
                          ' 配列の最初の要素が続く。

このフォーマットは読み書きが簡単で、DXTn 圧縮だけでなく、アルファやマルチ ミップ レベルなどの機能もサポートする。DirectX SDK の Compress サンプル アプリケーションでは、DDS ファイルを正しくインポートする方法を示している。

DXTn 圧縮したテクスチャを使用するために DDS フォーマットを使う必要はなく、その逆の場合も同様であるが、これら 2 つは連携している。

ミップマップ

ミップマップは、複数の解像度であらかじめフィルタ処理されたテクスチャ イメージを提供することによって、画質を向上させ、テクスチャ メモリの帯域幅を減少させる手法である。

DxTex のミップマップを生成するには、ソース イメージの幅と高さが共に 2 の累乗になっている必要がある。このミップマップを生成するには、[Format] メニューの [Generate Mip Maps] をクリックする。フィルタリングは、単純なボックス フィルタで実行される。つまり、最も近い 4 つのピクセルが平均化されて目的のピクセルが作成される。

アルファ

多くのテクスチャ フォーマットには、各ピクセルの不透明度の情報を提供するアルファ チャネルが含まれている。DxTex はテクスチャにおけるアルファを完全サポートする。.bmp ファイルをインポートする場合に、サイズが同じ 2 つのファイルが存在し、その一方のファイル名が "_a" で終わるときには (Sample.bmp および Sample_a.bmp など)、"_a" で終わるファイルがアルファ チャネルとしてロードされる。この 2 つ目の .bmp の青のチャネルがアルファ チャネルに格納される。ドキュメントを開いた後は、[File] メニューの [Open As Alpha Channel] をクリックして、明示的に .bmp ファイルをアルファ チャネルとしてロードできる。

アルファ チャネルを RGB チャネルなしで直接表示するには、[View] メニューの [Alpha Channel Only] をクリックする。アルファ チャネルがグレースケール イメージとして表示される。アルファ チャネルがロードされていない場合、すべてのピクセルでアルファ チャネルは 100 パーセントとなり、[Alpha Channel Only] を選択するとイメージが白く塗りつぶされる。アルファ チャネルを非表示にするには、[Alpha Channel Only] をもう一度クリックする。

通常のビューではアルファ チャネルのエフェクトが目に見えるが、これは、ウィンドウがバックグラウンド カラーで塗りつぶされており、アルファ チャネルが 100 パーセント未満のテクスチャでは、そのカラーが透けて見えるからである。バックグラウンド カラーを変更するには、[View] メニューの [Change Background Color] をクリックする。この選択を実行しても、テクスチャそのもの、またはファイルを保存するときに書き込まれるデータには影響しない。

DXT2 および DXT4 フォーマットでは、あらかじめ計算されたアルファが使用される。つまり、サーフェスに格納される赤、緑、および青の値には、対応するアルファ値が既に乗算されている。Direct3D では、あらかじめ計算されたアルファが含まれるサーフェスから、あらかじめ計算されていないアルファが含まれるサーフェスへのコピーはできない。したがって、DxTex の処理によっては、DXT2 および DXT4 フォーマットでは実行できないものもある。たとえば、アルファ チャネルとして開く、DXT3 への変換、DXT5 への変換などがそうである。DXTn テクスチャをサポートしない Direct3D デバイス では、これらのフォーマットを使用したテクスチャをサポートすることは難しい。これは、Direct3D ではこれらのフォーマットを従来の ARGB サーフェスにもコピーできないためである (ARGB サーフェスでもあらかじめ計算されたアルファが使用されている場合はコピーできるが、このような場合はまれである)。このような理由から、可能であれば DXT2 より DXT3 を、DXT4 より DXT5 を使用する方が簡単である。

コマンド ライン オプション

コマンドライン オプションを使って、入力ファイル、出力ファイル名、および処理オプションを DxTex に渡すことができる。出力ファイル名を指定した場合は、その出力ファイルを書き込んだ後にプログラムが自動終了し、ユーザー インターフェイスは表示されない。

dxtex [infilename] [-a alphaname] [-m] [DXT1|DXT2|DXT3|DXT4|DXT5] [outfilename]

infilename:               ロードするファイルの名前。
                          .bmp または DDS ファイルが可能。

-a alphaname:             次のパラメータはアルファ チャネルとして
                          ロードする .bmp ファイルの名前。
                          アルファ ファイル名を指定しないと、DxTex は
                          Infilename_a.bmp. という名のファイルを探し、
                          アルファ チャネルとして使用することに
                          注意すること。

-m:                       ミップマップが生成される。

DXT1|DXT2|DXT3|DXT4|DXT5: 圧縮フォーマット。フォーマットを指定しないと
                          イメージは ARGB-8888 となる。

outfilename:              出力ファイル名。  このオプションを指定しないと
                          ユーザー インターフェイスは現在のファイルと
                          すべての必要な操作を表示する。
                          出力ファイル名を指定すると、
                          アプリケーションはセーブ後、
                          ユーザー インターフェイスを表示せずに
                          終了する。


PixelShader サンプル

説明

このサンプルでは、ピクセル シェーダを使用して実現できるいくつかのエフェクトを示す。8 つのサムネールでは、それぞれ異なるピクセル シェーダを使用して、矩形をレンダリングしている。ピクセル シェーダでは、ピクセル単位の 3D デバイスによって実行される命令セットを使用し、さまざまな入力に基づきピクセルの色に影響を与える。ピクセル シェーダは、テクスチャ ステージ パイプラインの代わりに使用できる。

ピクセル シェーダの一部の機能しかサポートしていないカードもある。ピクセル シェーダの詳細については、「ピクセル シェーダ」を参照すること。

パス

ソース :(SDK ルート)\Samples\Multimedia\VBSamples\Direct3D\PixelShader

実行可能ファイル :(SDK ルート)\Samples\Multimedia\VBSamples\Direct3D\Bin

プログラミング上の注意

このサンプルでは、ヘルパー関数などのプログラミング要素から構成される Microsoft® DirectX® コードを使用する。このコードは、DirectX SDK のほかのサンプルと共有されている。共通のソース コードは、(SDK ルート)\Samples\Multimedia\VBSamples\Common にある。


PointSprites サンプル

説明

PointSprites サンプルでは、Microsoft® Direct3D® の新しいポイント スプライト機能の使い方を示す。ポイント スプライトとは、(x,y,z) 位置座標によってのみ参照される前向きの、テクスチャ処理された四角形である。ポイント スプライトは、粒子システムおよび関連エフェクトでよく使用される。

ポイント スプライトの一部の機能しかサポートしていないカードもある。ポイント スプライトの詳細については、「ポイント スプライト」を参照すること。

パス

ソース :(SDK ルート)\Samples\Multimedia\VBSamples\Direct3D\PointSprites

実行可能ファイル :(SDK ルート)\Samples\Multimedia\VBSamples\Direct3D\Bin

ユーザーズ ガイド

次の表は実装されているキーを示している。

キー | 動作
F2 | 新しいレンダリング デバイスまたはディスプレイ モードの選択を求めるメッセージを表示する。
Alt + Enter | フルスクリーン モードとウィンドウ モードを切り替える。
Esc | アプリケーションを終了する。

プログラミング上の注意

Direct3D サポートを使用しない場合、ポイント スプライトは各フレームを (ビルボードと同様に) 視点の方に向ける 4 つの頂点を使って実装できる。Direct3D を使用する場合は、ポイント スプライトの中心位置と半径によって、各ポイント スプライトを参照できる。これによって、プロセッサの計算時間と、頂点情報をグラフィックス カードにアップロードするときの帯域幅を節約できる。

このサンプルでは、各粒子システムは、複数のアルファ ブレンディングされたポイント スプライトを使用し、パーティクルにモーション ブラー エフェクトを与えて実現されている。

このサンプルでは、ヘルパー関数などのプログラミング要素から構成される Microsoft DirectX® コードを使用する。このコードは、DirectX SDK のほかのサンプルと共有されている。共通のソース コードは、(SDK ルート)\Samples\Multimedia\VBSamples\Common にある。


ScatterGraph サンプル

説明

ScatterGraph サンプルでは、Microsoft® Direct3D® を使用してグラフ表示する方法を示す。このサンプルでは、D3DX フレームワークの RenderToSurface 機能を使用して、テキストおよびビットマップを動的にレンダリングする。

パス

ソース :(SDK ルート)\Samples\Multimedia\VBSamples\Direct3D\AnimKeys

実行可能ファイル :(SDK ルート)\Samples\Multimedia\VBSamples\Direct3D\Bin

ユーザーズ ガイド

サンプルのインターフェイスを右クリックして、ショートカット メニューを表示する。次の表は、使用可能なメニュー コマンドを示している。

コマンド | 動作
[Load Data From File] | .csv (カンマ区切り) ファイルから新しいデータをロードする。.csv ファイルは、Microsoft Excel またはその他のスプレッドシート プログラムからエクスポートできる。
[Reset Orientation] | ビューポイントを既知の状態にリセットする。
[Show Connecting Lines] | データの順序が重要な場合に、データ ポイントを接続する。
[Show Height Lines] | その他の値と比べて y 値を簡単に表示できる。
[Show Foot Lines] | x-z 関係を簡単に表示できる。
[Show Base Plane] | y=0 の平面を表示する。
[Auto Rotate] | 回転のオンとオフを切り替える。

このファイルは、先頭の行および列が、データにタイトル付けするヘッダーとなるようにフォーマットする必要がある。ヘッダーには、この部分にピクチャが含まれていることを示すタグ TEXTURE:filename.bmp を指定できる。残りのデータ部は数値でなければならない。例については、(SDK ルート)\Samples\Multimedia\VBSamples\Media の Bargraphdata.csv を参照すること。

マウス ボタンを押さえてドラッグすると、グラフが回転する。

次の表は実装されているキーを示している。

キー | 動作
→ | カメラを右に移動する。
← | カメラを左に移動する。
↑ | カメラを上に移動する。
↓ | カメラを下に移動する。
W | カメラを前方に移動する。
S | カメラを後方に移動する。
E | カメラを右に回転する。
Q | カメラを左に回転する。
A | カメラを上に回転する。
Z | カメラを下に回転する。

プログラミング上の注意

このサンプルでは、ヘルパー関数などのプログラミング要素から構成される Microsoft DirectX® コードを使用する。このコードは、DirectX SDK のほかのサンプルと共有されている。共通のソース コードは、(SDK ルート)\Samples\Multimedia\VBSamples\Common にある。


SkinnedMesh サンプル

説明

SkinnedMesh サンプルでは、Microsoft® Direct3D® フレームワークを使用して、スキニングおよびアニメーション情報を含む .x ファイルをロードする方法を示す。

パス

ソース :(SDK ルート)\Samples\Multimedia\VBSamples\Direct3D\SkinnedMesh

実行可能ファイル :(SDK ルート)\Samples\Multimedia\VBSamples\Direct3D\Bin

ユーザーズ ガイド

次の表は、実装されているキーを示している。

キー | 動作
F2 | 新しいレンダリング デバイスまたはディスプレイ モードの選択を求めるメッセージを表示する。
Alt + Enter | フルスクリーン モードとウィンドウ モードを切り替える。
Esc | アプリケーションを終了する。

プログラミング上の注意

D3DUtil_LoadFromFileAsSkin に渡される最後の引数は、.x ファイル内のすべてのアニメーションの親となる CD3DAnimation クラスである。

Animation.SetTime を呼び出す必要があるが、モデルは配置されない。

Character.UpdateFrames は、キャラクタ上のすべての結合部について行列を計算する。

Character.RenderSkin は、ロードされたスキンを使用して、キャラクタをレンダリングする。

このサンプルでは、ヘルパー関数などのプログラミング要素から構成される Microsoft DirectX® コードを使用する。このコードは、DirectX SDK のほかのサンプルと共有されている。共通のソース コードは、(SDK ルート)\Samples\Multimedia\VBSamples\Common にある。

DirectX SDK の Extras ディレクトリのモデリング エクスポータは、スキニング情報を使用して .x ファイルへのエクスポートを行うことができる。


VertexBlend サンプル

説明

VertexBlend サンプルでは、頂点ブレンディングと呼ばれる手法 (サーフェス スキニングとも呼ばれる) を示す。このサンプルでは、さまざまなポイントで曲がるように作成されたファイル ベースのオブジェクトを表示する。サーフェス スキニングは、なめらかな結合部や、キャラクタ アニメーションでの肉付けなどのエフェクトに使用される手法である。

頂点ブレンディングの一部の機能しかサポートしていないディスプレイ カードもある。頂点ブレンディングの詳細については、「インデックス付き頂点ブレンディング」を参照すること。

パス

ソース :(SDK ルート)\Samples\Multimedia\VBSamples\Direct3D\VertexBlend

実行可能ファイル :(SDK ルート)\Samples\Multimedia\VBSamples\Direct3D\Bin

ユーザーズ ガイド

次の表は、実装されているキーを示している。

キー | 動作
F2 | 新しいレンダリング デバイスまたはディスプレイ モードの選択を求めるメッセージを表示する。
Alt + Enter | フルスクリーン モードとウィンドウ モードを切り替える。
Esc | アプリケーションを終了する。

プログラミング上の注意

頂点ブレンディングでは、各頂点にブレンドの重みを関連付ける必要がある。複数のワールド トランスフォームが SetTransformState を使って設定され、ブレンドの重みによって、各頂点を配置するときに各ワールド行列にどの程度影響するかを決定する。

このサンプルでは、共通ヘルパー コードを使ってメッシュがロードされる。独自の頂点および独自の FVF がどのように宣言され、メッシュの構築に使用されているかに注意すること。メッシュ オブジェクトについては、SetFVF の呼び出しを参照すること。メッシュ ヘルパー コードを使用しない場合も、この手法は同じである。ブレンドの重みを持つ頂点を格納する頂点バッファを作成し、適切な FVF を使用する。

このサンプルでは、ヘルパー関数などのプログラミング要素から構成される Microsoft® DirectX® コードを使用する。このコードは、DirectX SDK のほかのサンプルと共有されている。共通のソース コードは、(SDK ルート)\Samples\Multimedia\VBSamples\Common にある。


VertexShader サンプル

説明

VertexShader サンプルでは、頂点シェーダを使用して実現できるいくつかのエフェクトを示す。頂点シェーダは、3D デバイスによって頂点ごとに実行される命令セットを使用する。この命令は、興味深い方法で頂点のプロパティ (位置、法線、色、テクスチャ座標など) に影響を与える。

頂点シェーダの一部の機能しかサポートしていないカードもある。頂点シェーダの詳細については、「頂点シェーダ」を参照すること。

パス

ソース :(SDK ルート)\Samples\Multimedia\VBSamples\Direct3D\VertexShader

実行可能ファイル :(SDK ルート)\Samples\Multimedia\VBSamples\Direct3D\Bin

ユーザーズ ガイド

次の表は、実装されているキーを示している。

キー | 動作
F2 | 新しいレンダリング デバイスまたはディスプレイ モードの選択を求めるメッセージを表示する。
Alt + Enter | フルスクリーン モードとウィンドウ モードを切り替える。
Esc | アプリケーションを終了する。

プログラミング上の注意

このサンプルでは、ヘルパー関数などのプログラミング要素から構成される Microsoft® DirectX® コードを使用する。このコードは、DirectX SDK のほかのサンプルと共有されている。共通のソース コードは、(SDK ルート)\Samples\Multimedia\VBSamples\Common にある。


Direct3D Visual Basic リファレンス

ここでは、Microsoft® Direct3D® が提供する API 要素のリファレンス情報を記述する。リファレンス情報は以下のカテゴリに分類される。

  • クラス
  • 関数
  • 頂点シェーダ宣言子関数
  • 型
  • 列挙
  • テクスチャ引数フラグ
  • 柔軟な頂点フォーマット フラグ
  • FOURCC コード
  • エラー コード


クラス

ここでは、Microsoft® Direct3D® が提供するクラスのリファレンス情報を記述する。Direct3D では、次のクラスが使われる。

  • Direct3D8
  • Direct3DBaseTexture8
  • Direct3DCubeTexture8
  • Direct3DDevice8
  • Direct3DIndexBuffer8
  • Direct3DResource8
  • Direct3DSurface8
  • Direct3DSwapChain8
  • Direct3DTexture8
  • Direct3DVertexBuffer8
  • Direct3DVolume8
  • Direct3DVolumeTexture8


Direct3D8

Microsoft® Direct3D® オブジェクトを作成し、オブジェクトの環境をセットアップするには、Direct3D8 クラスのメソッドを使用する。このクラスには、デバイスの能力を列挙および取得するためのメソッドが含まれる。

Direct3D8 クラスを取得するには、DirectX8.Direct3DCreate メソッドを呼び出す。

Direct3D8 クラスのメソッドは、以下のグループにまとめることができる。

生成 | CreateDevice
列挙 | EnumAdapterModes
情報 | GetAdapterCount
 | GetAdapterDisplayMode
 | GetAdapterIdentifier
 | GetAdapterModeCount
 | GetAdapterMonitor
 | GetDeviceCaps
登録 | RegisterSoftwareDevice
検査 | CheckDepthStencilMatch
 | CheckDeviceFormat
 | CheckDeviceMultiSampleType
 | CheckDeviceType

参照

DirectX8.Direct3DCreate


Direct3D8.CheckDepthStencilMatch

サーフェスのフォーマットが、指定したリソース タイプとして利用できるかどうか、およびこのアダプタを使用するデバイスでテクスチャ、深度ステンシル バッファ、レンダリング ターゲットのいずれか、またはこれら 3 つの組み合わせとして使用できるかどうかを調べる。

object.CheckDepthStencilMatch( _
    Adapter As Long, _
    DeviceType As  CONST_D3DDEVTYPE, _
    AdapterFormat As CONST_D3DFORMAT, _
    RenderTargetFormat As CONST_D3DFORMAT, _
    DepthStencilFormat As CONST_D3DFORMAT) As Long

指定項目

object
Direct3D8 オブジェクトを表すオブジェクト式。
Adapter
照会するディスプレイ アダプタを示す序数。D3DADAPTER_DEFAULT は常にプライマリ ディスプレイ アダプタである。
DeviceType
デバイス タイプを識別する CONST_D3DDEVTYPE 列挙のメンバ。
AdapterFormat
CONST_D3DFORMAT 列挙のメンバ。アダプタで使用されるディスプレイ モードのフォーマットを識別する。
RenderTargetFormat
テストするレンダリング ターゲット サーフェスのフォーマットを識別する CONST_D3DFORMAT 列挙のメンバ。
DepthStencilFormat
テストする深度ステンシル サーフェスのフォーマットを識別する CONST_D3DFORMAT 列挙のメンバ。

戻り値

深度ステンシル フォーマットが、ディスプレイ モードのターゲット レンダリング フォーマットと互換性がある場合、このメソッドは D3D_OK を返す。

引数の 1 つ以上が無効な場合は、D3DERR_INVALIDCALL が返される場合がある。深度ステンシル フォーマットが、ディスプレイ モードのターゲット レンダリング フォーマットと互換性がない場合、このメソッドは D3DERR_NOTAVAILABLE を返す。

エラー コード

このメソッドでは、Err.Number は設定されていない。

注意

このメソッドは、特定の深度フォーマットが特定のレンダリング ターゲット フォーマットでのみ機能するハードウェア レンダリングでアプリケーションが機能できるようにするために用意されている。次のコードは、CheckDeviceFormat を使用して深度ステンシル フォーマットを検証する方法を示している。

Function IsDepthFormatOK( DepthFormat As CONST_D3DFORMAT, AdapterFormat As CONST_D3DFORMAT, _
                          BackBufferFormat As CONST_D3DFORMAT) as Boolean

      Dim check As Long

      check = d3d.CheckDeviceFormat(D3DADAPTER_DEFAULT, D3DDEVTYPE_HAL, AdapterFormat, _
                                    D3DUSAGE_DEPTHSTENCIL, D3DRTYPE_SURFACE, DepthFormat)
      If (check < 0) Then Exit Function   ' FALSE を返す。

      check = d3d.CheckDepthStencilFormat(D3DADAPTER_DEFAULT, D3DDEVTYPE_HAL, AdapterFormat, _
                          RenderTargetFormat, DepthFormat)
      If (check < 0) Then
         IsDepthStencilFormatOK = False
      Else
         IsDepthStencilFormatOK = True
      End If

End function

上の呼び出しは、DepthFormat が AdapterFormat および BackBufferFormat と組み合わせて使用できない場合、FALSE を返す。


Direct3D8.CheckDeviceFormat

サーフェスのフォーマットが、指定したリソース タイプとして利用できるかどうか、およびこのアダプタを使用するデバイスでテクスチャ、深度ステンシル バッファ、レンダリング ターゲットのいずれか、またはこれら 3 つの組み合わせとして使用できるかどうかを調べる。

object.CheckDeviceFormat( _
    Adapter As Long, _
    DeviceType As  CONST_D3DDEVTYPE, _
    AdapterFormat As CONST_D3DFORMAT, _
    Usage As Long, _
    RType As CONST_D3DRESOURCETYPE, _
    CheckFormat As CONST_D3DFORMAT) As Long

指定項目

object
Direct3D8 オブジェクトを表すオブジェクト式。
Adapter
照会するディスプレイ アダプタを示す序数。D3DADAPTER_DEFAULT は常にプライマリ ディスプレイ アダプタである。この値がシステムのディスプレイ アダプタの数以上の場合、このメソッドは D3DERR_INVALIDCALL を返す。
DeviceType
デバイス タイプを識別する CONST_D3DDEVTYPE 列挙のメンバ。
AdapterFormat
CONST_D3DFORMAT 列挙のメンバ。アダプタで使用されるディスプレイ モードのフォーマットを識別する。
Usage
CheckFormat のサーフェスに対して要求する使用方法。CONST_D3DUSAGEFLAGS 列挙で定義されている次のフラグのどちらか一方または両方を指定できる。
D3DUSAGE_DEPTHSTENCIL
深度ステンシル サーフェスとして使用できるサーフェスであることを示す。
D3DUSAGE_RENDERTARGET
レンダリング ターゲットとして使用できるサーフェスであることを示す。RType パラメータの値が明確に特定の用途を示唆している場合、アプリケーションは Usage パラメータを 0 にしておくことができる。
RType
CONST_D3DRESOURCETYPE 列挙のメンバ。調査するフォーマットと共に使用することを要求するリソース タイプを指定する。
CheckFormat
CONST_D3DFORMAT 列挙のメンバ。Usage で指定した方法で使用するサーフェスのフォーマットを示す。

戻り値

フォーマットが、要求された使用方法について、指定されたデバイスと互換性がある場合、このメソッドは D3D_OK を返す。

Adapter がシステムのディスプレイ アダプタの数以上の場合、または DeviceType がサポートされていない場合、このメソッドは D3DERR_INVALIDCALL を返す。フォーマットがこの使用方法についてデバイスで受け入れられない場合、このメソッドは D3DERR_NOTAVAILABLE を返す。

エラー コード

このメソッドでは、Err.Number は設定されていない。

注意

CheckDeviceFormat の一般的な用途は、特定の深度ステンシル サーフェス フォーマットが存在するかどうかを確認することである。列挙処理の詳細については、「デバイスの選択」を参照すること。CheckDeviceFormat のもう 1 つの一般的な用途は、特定のサーフェス フォーマットに存在するテクスチャを、現在のディスプレイ モードでレンダリングできるかどうかを確認することである。

Function DoesDepthFormatExist(DepthFormat As CONST_D3DFORMAT, AdapterFormat As CONST_D3DFORMAT) As Boolean

   Dim Check As Long
   Dim D3D As Direct3D8

   'D3D オブジェクトが作成され、初期化済みであると仮定する。
   Check = D3D.CheckDeviceFormat(D3DADAPTER_DEFAULT, D3DDEVTYPE_HAL, AdapterFormat, _
                                 D3DUSAGE_DEPTHSTENCIL, D3DRTYPE_SURFACE, DepthFormat)
   If (Check >= 0) Then
       DoesDepthFormatExist= True
   Else
      DoesDepthFormatExist= False
   End If

End Function

上の関数の呼び出しは、システムに DepthFormat が存在しない場合は FALSE を返す。

CheckDeviceFormat のもう 1 つの一般的な用途は、特定のサーフェス フォーマットに存在するテクスチャを、現在のディスプレイ モードでレンダリングできるかどうかを確認することである。次のコードは、CheckDeviceFormat を使用して、テクスチャ フォーマットが特定のバック バッファ フォーマットと互換性があるかどうかを確認する方法を示している。

Function IsTextureFormatOk(TextureFormat As D3DFORMAT ,AdapterFormat As D3DFORMAT ) As Boolean
   Dim Check As Long
   Dim D3D As Direct3D8

   Check = D3D.CheckDeviceFormat( D3DADAPTER_DEFAULT, D3DDEVTYPE_HAL, AdapterFormat, _
                                  0, D3DRTYPE_TEXTURE, TextureFormat)

   If (Check >= 0) Then
      IsTextureFormatOk = True
   Else
      IsTextureFormatOk = False
   End If

End Function

上の呼び出しは、アダプタ サーフェス フォーマットが AdapterFormat であるときに、TextureFormat を使ってテクスチャをレンダリングできない場合、FALSE を返す。


Direct3D8.CheckDeviceMultiSampleType

このデバイスでマルチサンプリング テクニックを利用できるかどうかを調べる。

object.CheckDeviceMultiSampleType( _
    Adapter As Long, _
    DeviceType As CONST_D3DDEVTYPE, _
    Format As CONST_D3DFORMAT, _
    Windowed As Long, _
    MultiSampleType As CONST_D3DMULTISAMPLE_TYPE) As Long

指定項目

object
Direct3D8 オブジェクトを表すオブジェクト式。
Adapter
照会するディスプレイ アダプタを示す序数。D3DADAPTER_DEFAULT は常にプライマリ ディスプレイ アダプタである。Adapter の値がシステムのディスプレイ アダプタの数以上の場合、このメソッドは FALSE (0) を返す
DeviceType
デバイス タイプを識別する CONST_D3DDEVTYPE 列挙のメンバ。
Format
CONST_D3DFORMAT 列挙のメンバ。サーフェスに対して要求するマルチサンプリング タイプのセットを指定する。「注意」を参照すること。
Windowed
ウィンドウ マルチサンプリングについて問い合わせるときは TRUE を指定し、フルスクリーン マルチサンプリングについて問い合わせるときは FALSE を指定する。
MultiSampleType
CONST_D3DMULTISAMPLE_TYPE 列挙のメンバ。検査するマルチサンプリング テクニックを指定する。

戻り値

デバイスが、指定されたマルチサンプリング メソッドを実行できる場合、このメソッドは D3D_OK を返す。

失敗した場合は、次のいずれかの値を返す。

D3DERR_INVALIDCALL
D3DERR_INVALIDDEVICE
D3DERR_NOTAVAILABLE

注意

このメソッドは、レンダリング ターゲットおよび深度ステンシル サーフェスの両方で使用するためのものである。これは、この 2 つ一緒に使用する場合、両方をマルチサンプリングして作成する必要があるからである。

次のコードは、CheckDeviceMultiSampleType を使って、デバイスが特定のマルチサンプリング メソッドをサポートするかどうかをテストする方法を示している。

Dim Device As Direct3DDevice8
Dim Caps As D3DCAPS8
Dim Caps2 As CONST_D3DDEVTYPE
Dim Mode As CONST_D3DFORMAT

If Device.CheckDeviceMultiSampleType(Caps.AdapterOrdinal, Caps2.DeviceType, _
                                     Mode.Format, False, D3DMULTISAMPLE_3_SAMPLES) Then
    ' D3DMULTISAMPLE_3_SAMPLES が、フルスクリーン モードで、
    ' 指定されたサーフェス フォーマットについて機能する場合の処理。
End If

エラー コード

このメソッドでは、Err.Number は設定されていない。


Direct3D8.CheckDeviceType

このアダプタで特定のデバイス タイプを使用して、特定のフォーマットを使ったハードウェア アクセラレーションを期待できるかどうかを確認する。

object.CheckDeviceType( _
    Adapter As Long, _
    CheckType As CONST_D3DDEVTYPE, _
    DisplayFormat As CONST_D3DFORMAT, _
    BackBufferFormat As CONST_D3DFORMAT, _
    bWindowed As Long) As Long

指定項目

object
Direct3D8 オブジェクトを表すオブジェクト式。
Adapter
列挙するディスプレイ アダプタを示す序数。D3DADAPTER_DEFAULT は常にプライマリ ディスプレイ アダプタである。この値がシステムのディスプレイ アダプタの数以上の場合、このメソッドは D3DERR_INVALIDCALL を返す。
CheckType
CONST_D3DDEVTYPE 列挙のメンバ。検査するデバイス タイプを示す。
DisplayFormat
CONST_D3DFORMAT 列挙のメンバ。デバイス タイプを検査するアダプタ ディスプレイ モードのフォーマットを示す。たとえば、デバイスによっては、ピクセル単位の 16 ビットのモードでのみ動作する。
BackBufferFormat
CONST_D3DFORMAT 列挙のメンバ。デバイス タイプを検査するアダプタ ディスプレイ モードのフォーマットを示す。たとえば、デバイスによっては、ピクセル単位の 16 ビットのモードでのみ動作する。
bWindowed
デバイス タイプがフルスクリーン モードとウィンドウ モードのいずれで使用されるかを指定する値。TRUE に設定した場合、ウィンドウ アプリケーションの照会が実行される。それ以外の場合は、この値を FALSE に設定することが望ましい。

戻り値

このアダプタでデバイスを使用できる場合は、D3D_OK を返す。

Adapter がシステムのディスプレイ アダプタの数以上の場合、このメソッドは D3DERR_INVALIDCALL を返す。CheckType が存在しないデバイスを指定していた場合、このメソッドは D3DERR_INVALIDDEVICE を返す。サーフェス フォーマットがサポートされていないか、指定されたフォーマットでハードウェア アクセラレーションが使用できない場合は、D3DERR_NOTAVAILABLE を返す。

エラー コード

このメソッドでは、Err.Number は設定されていない。

注意

使用できない可能性のある最も重要なデバイス タイプは D3DDEVTYPE_HAL である。D3DDEVTYPE_HAL にはハードウェア アクセラレーションが必要である。アプリケーションでは、CheckDeviceType を使って、必要なハードウェアとドライバがシステムにあるかどうかを確認する必要がある。使用できない可能性のあるもう 1 つのデバイスは D3DDEVTYPE_SW である。このデバイス タイプは、Direct3D8.RegisterSoftwareDevice を使って登録されたプラグ可能なソフトウェア デバイスを表す。

アプリケーションでは、アルファ チャネルを含む DisplayFormat を指定すべきではない。この場合、呼び出しは失敗する。アルファ チャネルはバック バッファに存在している場合があるが、2 つのディスプレイ フォーマットはほかのすべての面で同じでなければならない。たとえば、DisplayFormat が D3DFMT_X1R5G5B5 である場合、BackBufferFormat の有効な値には D3DFMT_X1R5G5B5 および D3DFMT_A1R5G5B5 は含まれるが、D3DFMT_R5G6B5 は除外される。

次のコードは、デフォルトのアダプタが、ハードウェア アクセラレーションを使って、ウィンドウ モードで RGB565 カラーを処理するかどうかをチェックする。

     Dim DisplayFormat As CONST_D3DFORMAT, BackBufferFormat As CONST_D3DFORMAT
     Dim IsWindowed As Long, bModeOK As Boolean, Check As Long

             DisplayFormat = D3DFMT_R5G6B5
             BackBufferFormat = D3DFMT_R5G6B5
     IsWindowed = 1     'TRUE

     Check = d3d.CheckDeviceType(D3DADAPTER_DEFAULT, D3DDEVTYPE_HAL, DisplayFormat, BackBufferFormat, IsWindowed)
     If (Check >= 0) Then
         bModeOK = True
     Else
         bModeOK = False
     End If


Direct3D8.CreateDevice

ディスプレイ アダプタを表すためのデバイスを作成する。

object.CreateDevice( _
    Adapter As Long, _
    DeviceType As CONST_D3DDEVTYPE, _
    hFocusWindow As Long, _
    BehaviorFlags As Long, _
    PresentationParameters As D3DPRESENT_PARAMETERS) As Direct3DDevice8

指定項目

object
Direct3D8 オブジェクトを表すオブジェクト式。
Adapter
ディスプレイ アダプタを示す序数。D3DADAPTER_DEFAULT は常にプライマリ ディスプレイ アダプタである。
DeviceType
CONST_D3DDEVTYPE 列挙のメンバ。目的のデバイスのタイプを示す。目的のデバイス タイプが使用できない場合、このメソッドは失敗する。
hFocusWindow
この Direct3D デバイスでフォーカスを設定するウィンドウ ハンドル。指定するウィンドウは、フルスクリーンの最上位ウィンドウでなければならない。
BehaviorFlags
Microsoft® Direct3D® デバイスの全体的な動作を制御する、CONST_D3DCREATEFLAGS 列挙で定義されている 1 つ以上のフラグの組み合わせ。
PresentationParameters
作成するデバイスのプレゼンテーション パラメータを示す D3DPRESENT_PARAMETERS 型。CreateDevice を呼び出すと、D3DPRESENT_PARAMETERS の BackBufferCount メンバの値が変更される場合がある。バック バッファ カウントは、バック バッファの正しい数を反映して変更される。

戻り値

このメソッドは、作成されたデバイスを表す Direct3DDevice8 オブジェクトを返す。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DERR_NOTAVAILABLE
D3DERR_OUTOFVIDEOMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

このメソッドからは、要求したディスプレイ モード (またはウィンドウ) に設定されて、適切なバック バッファが割り当てられた、完全に動作するデバイス オブジェクトが返る。アプリケーションは、必要に応じて深度バッファを作成して設定するだけで、レンダリングを開始できる。

参照

Direct3DDevice8.Reset、D3DDEVICE_CREATION_PARAMETERS


Direct3D8.EnumAdapterModes

アダプタのディスプレイ モードを列挙する。

object.EnumAdapterModes( _
    Adapter As Long, _
    Mode As Long, _
    DisplayMode As D3DDISPLAYMODE)

指定項目

object
Direct3D8 オブジェクトを表すオブジェクト式。
Adapter
照会するディスプレイ アダプタを示す序数。D3DADAPTER_DEFAULT は常にプライマリ ディスプレイ アダプタである。
Mode
列挙するモードを示す番号。D3DCURRENT_DISPLAY_MODE はアダプタの現在のデスクトップ ディスプレイ モードを示す特別な値であり、このメソッドでは指定できない。
DisplayMode
指定したモードを記述する情報が格納される D3DDISPLAYMODE 型。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DERR_OUTOFVIDEOMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

一部のディスプレイ ドライバには、モード数を大幅に増加させるリフレッシュ レート情報を含んでいる。古いドライバでは、D3DADAPTER_DEFAULT のリフレッシュ レートだけが列挙される。Direct3D では、モニタの能力に応じて、ディスプレイ モードおよびリフレッシュ レートを制限しようとする。それでも、列挙されたモードがシステムのモニタでサポートされていない可能性がある。Microsoft® Windows® のディスプレイ コントロール パネル ユーティリティで使用されるものと同様のディスプレイ モード テスト ユーティリティを実装できる。

Direct3D8.GetAdapterModeCount を使って、システムでサポートされているモードの総数を調べる。Mode パラメータの有効な値は、0 からモードの総数 - 1 までの範囲である。

参照

Direct3D8.GetAdapterModeCount


Direct3D8.GetAdapterCount

システムにあるアダプタの数を返す。

object.GetAdapterCount() As Long

指定項目

object
Direct3D8 オブジェクトを表すオブジェクト式。

戻り値

この Direct3D8 オブジェクトが作成された時点でシステムに存在しているアダプタの数を示す LONG の値。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DERR_OUTOFVIDEOMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

参照

Direct3D8.GetAdapterIdentifier


Direct3D8.GetAdapterDisplayMode

アダプタの現在のディスプレイ モードを取得する。

object.GetAdapterDisplayMode( _
    Adapter As Long, _
    Mode As D3DDISPLAYMODE)

指定項目

object
Direct3D8 オブジェクトを表すオブジェクト式。
Adapter
照会するディスプレイ アダプタを示す序数。D3DADAPTER_DEFAULT は常にプライマリ ディスプレイ アダプタである。
Mode
現在のアダプタのモードを記述する情報が格納される D3DDISPLAYMODE 型。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DERR_OUTOFVIDEOMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

アダプタを表すデバイスがアダプタのモード以外のモードにリセットされている場合があることに注意すること。この場合、デバイスが消失すると、アダプタの現在のモードは特定されない。この関数からは、デバイスに対して要求されている特定のモードではなく、アダプタのモードが返る。


Direct3D8.GetAdapterIdentifier

Direct3D8 オブジェクトが作成された時点でシステムに存在していた物理的なディスプレイ アダプタを記述する。

object.GetAdapterIdentifier( _
    Adapter As Long, _
    Flags As Long, _
    Identifier As D3DADAPTER_IDENTIFIER8)

指定項目

object
Direct3D8 オブジェクトを表すオブジェクト式。
Adapter
ディスプレイ アダプタを示す序数。D3DADAPTER_DEFAULT は常にプライマリ ディスプレイ アダプタである。このパラメータの最小値は 0 で、最大値は Direct3D8.GetAdapterCount で返される値から 1 を引いた値である。
Flags
通常は 0 (ゼロ) に設定するパラメータ。ただし、CONST_D3DCONST 列挙で定義されている次の値を指定することもできる。
D3DENUM_NO_WHQL_LEVEL
D3DADAPTER_IDENTIFIER8 型の WHQLLevel メンバを強制的に 0 (ゼロ) に設定する。この場合、WHQL の認証期日に関する情報は返されない。このフラグを設定すると、WHQL の認証期日を確認する際に発生する 1、2 秒の遅れを除くことができる。
Identifier
指定したアダプタを記述する情報が格納される D3DADAPTER_IDENTIFIER8 型。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DERR_OUTOFVIDEOMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

参照

Direct3D8.GetAdapterCount


Direct3D8.GetAdapterModeCount

アダプタで利用可能なディスプレイ モードの数を返す。

object.GetAdapterModeCount( _
    Adapter As Long) As Long

指定項目

object
Direct3D8 オブジェクトを表すオブジェクト式。
Adapter
ディスプレイ アダプタを示す序数。D3DADAPTER_DEFAULT は常にプライマリ ディスプレイ アダプタである。

戻り値

指定したアダプタのディスプレイ モードの数が返る。または、システムにあるアダプタの数以上の値を Adapter で指定すると、0 (ゼロ) が返る。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DERR_OUTOFVIDEOMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

参照

Direct3D8.EnumAdapterModes


Direct3D8.GetAdapterMonitor

Microsoft® Direct3D® オブジェクトに関連付けられているモニタのハンドルを返す。

object.GetAdapterMonitor( _
    Adapter As Long) As Long

指定項目

object
Direct3D8 オブジェクトを表すオブジェクト式。
Adapter
ディスプレイ アダプタを示す序数。D3DADAPTER_DEFAULT は常にプライマリ ディスプレイ アダプタである。

戻り値

Direct3D オブジェクトに関連付けられたモニタのハンドル。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DERR_OUTOFVIDEOMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

次のサンプル コードは、指定されたデバイスに関連付けられたモニタのハンドルを取得する方法を示している。このサンプルのように、Direct3DDevice8.GetDirect3D を使って、デバイスから Direct3D 列挙型を返し、Direct3DDevice8.GetCreationParameters を使って、Adapter の値を取得する。

    Dim Device As Direct3DDevice8, D3D As Direct3DDevice8
    Dim Parameters As D3DDEVICE_CREATION_PARAMETERS
    Dim MonitorHandle As Long

    ' 次のコードでは、上記のアイテムが正しく作成および初期化されたと仮定する。
    If ((Device.GetCreationParameters(Parameters) <= 0) And (Device.GetDirect3D(D3D) <= 0)) Then
        MonitorHandle = D3D.GetAdapterMonitor(Parameters.AdapterOrdinal)
    Else
        ' ここにエラー処理コードを配置する。
    End If

参照

Direct3DDevice8.GetCreationParameters、Direct3DDevice8.GetDirect3D


Direct3D8.GetDeviceCaps

デバイスについてのデバイス固有の情報を取得する。

object.GetDeviceCaps( _
    Adapter As Long, _
    DeviceType As CONST_D3DDEVTYPE, _
    Caps As D3DCAPS8)

指定項目

object
Direct3D8 オブジェクトを表すオブジェクト式。
Adapter
ディスプレイ アダプタを示す序数。D3DADAPTER_DEFAULT は常にプライマリ ディスプレイ アダプタである。
DeviceType
CONST_D3DDEVTYPE 列挙のメンバ。デバイスのタイプを示す。
Caps
デバイスの能力を記述した情報が格納される D3DCAPS8 型。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DERR_INVALIDDEVICE
D3DERR_OUTOFVIDEOMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic の「エラー処理」を参照すること。

注意

アプリケーションで、Microsoft® Direct3D® デバイス オブジェクト全体における頂点処理能力の持続性を仮定してはならない。物理デバイスが公開する特定の能力は、Direct3D8.CreateDevice に指定されるパラメータによって異なる。たとえば、このような能力は、ハードウェア頂点処理を有効にして Direct3D デバイス オブジェクトを作成する前後で、異なる頂点処理能力を提供できる。詳細については、「D3DCAPS8」を参照すること。


Direct3D8.RegisterSoftwareDevice

プラグ可能なソフトウェア デバイスをMicrosoft® Direct3D® に登録する。

object.RegisterSoftwareDevice( _
    InitializeFunction As Any)

指定項目

object
Direct3D8 オブジェクトを表すオブジェクト式。
InitializeFunction
登録するソフトウェア デバイスの初期化関数。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DERR_OUTOFVIDEOMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

Direct3D に対するソフトウェア ラスタ化は、プラグ可能なソフトウェア デバイスによって提供される。これにより、アプリケーションは、Direct3D オブジェクトを通してさまざまなソフトウェア ラスタライザにアクセスできる。ソフトウェア デバイスは、アプリケーションによってロードされて、Direct3D オブジェクトに登録される。この時点で、ソフトウェア デバイスを使ってレンダリングを実行する Direct3DDevice オブジェクトを作成できる。

Direct3D ソフトウェア デバイスは、ハードウェアのデバイス ドライバ インターフェイス (DDI) と似たインターフェイスを通して Direct3D と通信する。

Direct3D DDK では、プラグ可能なソフトウェア デバイスを開発するためのドキュメントとヘッダーが提供されている。


Direct3DBaseTexture8

キューブ テクスチャ、テクスチャ、ボリューム テクスチャなどのテクスチャ リソースを操作するには、Direct3DBaseTexture8 クラスのメソッドを使用する。

デバイスの特定のステージに割り当てられている Direct3DBaseTexture8 インターフェイスを取得するには、Direct3DDevice8.GetTexture メソッドを呼び出す。

Direct3DBaseTexture8 クラスは、次のようなグループに分類できる Direct3DResource8 メソッドを実装している。

デバイス | GetDevice
情報 | GetType
プライベート サーフェス データ | FreePrivateData
 | GetPrivateData
 | SetPrivateData
リソース管理 | GetPriority
 | PreLoad
 | SetPriority

Direct3DBaseTexture8 クラスのメソッドは、以下のグループにまとめることができる。

詳細 | GetLOD
 | SetLOD
情報 | GetLevelCount


Direct3DBaseTexture8.GetLevelCount

マルチレベル テクスチャのテクスチャ レベルの数を返す。

object.GetLevelCount() As Long

指定項目

object
Direct3DBaseTexture8 オブジェクトを表すオブジェクト式。

戻り値

マルチレベル テクスチャのテクスチャ レベルの数を示す Long 値。

エラー コード

失敗した場合はエラーが発生し、Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

対象

このメソッドは次のクラスに適用される。これらのクラスは、Direct3DBaseTexture8 のメソッドを実装する。

  • Direct3DCubeTexture8
  • Direct3DTexture8
  • Direct3DVolumeTexture8


Direct3DBaseTexture8.GetLOD

管理下のテクスチャに設定されている最大詳細レベル (LOD) に制限された値を返す。

object.GetLOD() As Long

指定項目

object
Direct3DBaseTexture8 オブジェクトを表すオブジェクト式。

戻り値

最大 LOD 値に制限された LONG 値 (レベルの総数から 1 を引いた値)。

エラー コード

失敗した場合はエラーが発生し、Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

対象

このメソッドは次のクラスに適用される。これらのクラスは、Direct3DBaseTexture8 のメソッドを実装する。

  • Direct3DCubeTexture8
  • Direct3DTexture8
  • Direct3DVolumeTexture8

注意

GetLOD を使って、管理下のテクスチャの LOD 制御を行う。このメソッドは、非管理下のテクスチャに 0 を返す。

参照

Direct3DBaseTexture8.SetLOD


Direct3DBaseTexture8.SetLOD

管理下のテクスチャに最大詳細レベル (LOD) を設定する。

object.SetLOD( _
    LODNew As Long) As Long

指定項目

object
Direct3DBaseTexture8 オブジェクトを表すオブジェクト式。
LODNew
ミップマップ チェーンに設定する最大詳細 LOD の値。

戻り値

最大 LOD 値に制限された LONG 値 (レベルの総数から 1 を引いた値)。以降のこのメソッドの呼び出しでは、以前に設定された LOD 値ではなく、制限された値が返される。

エラー コード

失敗した場合はエラーが発生し、Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

対象

このメソッドは次のクラスに適用される。これらのクラスは、Direct3DBaseTexture8 のメソッドを実装する。

  • Direct3DCubeTexture8
  • Direct3DTexture8
  • Direct3DVolumeTexture8

注意

SetLOD は、管理下のテクスチャの LOD 制御のために使われる。このメソッドは、非管理下のテクスチャに 0 を返す。

SetLOD は、ローカル ビデオ メモリにロードするチェーンの中で最も詳細なミップマップを Microsoft® Direct3D® テクスチャ マネージャに通知する。たとえば、5 レベルのミップマップ チェーンにおいて LODNew で 2 を指定すると、テクスチャ マネージャは常にレベル 2 から 4 のミップマップだけをローカル ビデオ メモリにロードする。

さらに具体的に説明すると、256 × 256 のディメンジョンでテクスチャが作成されている場合、最大詳細レベルを 0 に設定すると利用可能な最大のミップマップが 256 × 256 であることを示し、最大詳細レベルを 1 に設定すると利用可能な最大ミップマップが 128 × 128 であることを示す。このようにして、チェーンの最大ミップ レベル (最も小さいテクスチャ サイズ) まで同様に示される。

参照

Direct3DBaseTexture8.GetLOD


Direct3DCubeTexture8

キューブ マップ リソースを扱うには、Direct3DCubeTexture8 クラスのメソッドを使用する。

Direct3DCubeTexture8 クラスを取得するには、Direct3DDevice8.CreateCubeTexture メソッドを呼び出す。

Direct3DCubeTexture8 クラスは、次のようなグループに分類できる Direct3DResource8 メソッドを実装している。

デバイス | GetDevice
情報 | GetType
プライベート サーフェス データ | FreePrivateData
 | GetPrivateData
 | SetPrivateData
リソース管理 | GetPriority
 | PreLoad
 | SetPriority

Direct3DCubeTexture8 クラスは、次のようなグループに分類できる Direct3DBaseTexture8 クラスを実装している。

詳細 | GetLOD
 | SetLOD
情報 | GetLevelCount

Direct3DCubeTexture8 クラスのメソッドは、以下のグループにまとめることができる。

情報 | GetLevelDesc
サーフェスのロック | LockRect
 | UnlockRect
その他 | AddDirtyRect
 | GetCubeMapSurface

参照

Direct3DDevice8.CreateCubeTexture


Direct3DCubeTexture8.AddDirtyRect

キューブ マップ リソースにダーティー領域を追加する。

object.AddDirtyRect( _
    FaceType  As CONST_D3DCUBEMAP_FACES, _
    DirtyRect As Any)

指定項目

object
Direct3DCubeTexture8 オブジェクトを表すオブジェクト式。
FaceType
キューブ マップのサーフェスを示す CONST_D3DCUBEMAP_FACES 列挙のメンバ。
DirtyRect
ダーティー領域を指定する RECT 型。ByVal 0 を指定すると、キューブ テクスチャ全体を覆うようにダーティー領域が拡大する。

エラー コード

失敗した場合はエラーが発生し、Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

パフォーマンスの理由によって、ダーティーな範囲はテクスチャのレベル ゼロに対して記録されるのみである。サブレベルについては、対応する (スケールされた) 矩形またはボックスもダーティーであると仮定される。D3DLOCK_NO_DIRTY_UPDATE または D3DLOCK_READONLY なしで LockRect か LockBox が呼び出されたとき、ダーティーな範囲は自動的に記録される。また CopyRects 呼び出しの宛先サーフェスはダーティーとしてマークされる。

参照

Direct3DCubeTexture8.GetLevelDesc、Direct3DCubeTexture8.LockRect、Direct3DCubeTexture8.UnlockRect


Direct3DCubeTexture8.GetCubeMapSurface

キューブ マップのサーフェスを取得する。

object.GetCubeMapSurface( _
    FaceType As CONST_D3DCUBEMAP_FACES, _
    Level As Long) As Direct3DSurface8

指定項目

object
Direct3DCubeTexture8 オブジェクトを表すオブジェクト式。
FaceType
キューブ マップのサーフェスを識別する CONST_D3DCUBEMAP_FACES 列挙のメンバ。
Level
ミップマップ化キューブ テクスチャのレベルを指定する。

戻り値

キューブ マップのサーフェスを表す Direct3DSurface8 オブジェクトを返す。

エラー コード

失敗した場合はエラーが発生し、Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。


Direct3DCubeTexture8.GetLevelDesc

指定したキューブ テクスチャ レベルの記述を取得する。

object.GetLevelDesc( _
    Level As Long, _
    Desc As D3DSURFACE_DESC)

指定項目

object
Direct3DCubeTexture8 オブジェクトを表すオブジェクト式。
Level
ミップマップ化キューブ テクスチャのレベルを指定する。
Desc
指定したキューブ テクスチャ レベルを記述する D3DSURFACE_DESC 型。

エラー コード

失敗した場合はエラーが発生し、パラメータの 1 つ以上が無効な場合は、Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

参照

Direct3DCubeTexture8.AddDirtyRect、Direct3DCubeTexture8.LockRect、Direct3DCubeTexture8.UnlockRect


Direct3DCubeTexture8.LockRect

キューブ テクスチャ リソース上の矩形をロックする。

object.LockRect( _
    FaceType As CONST_D3DCUBEMAP_FACES, _
    Level As Long, _
    LockedRect As D3DLOCKED_RECT, _
    Rect As Any, _
    Flags As Long)

指定項目

object
Direct3DCubeTexture8 オブジェクトを表すオブジェクト式。
FaceType
キューブ マップのサーフェスを識別する CONST_D3DCUBEMAP_FACES 列挙のメンバ。
Level
ミップマップ化キューブ テクスチャのレベルを指定する。
LockedRect
ロックする領域が記述されている D3DLOCKED_RECT 型。
Rect
ロックする矩形。RECT 型によって指定される。または、ByVal 0 の場合はテクスチャ全体を覆うようにダーティー領域が拡大する。
Flags
実行するロックの種類を記述する CONST_D3DLOCKFLAGS 列挙によって定義される 0 個以上の有効なロッキング フラグの組み合わせ。

エラー コード

失敗した場合はエラーが発生し、Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

マルチサンプル バック バッファはロックできない。

パフォーマンスの理由によって、ダーティーな範囲はテクスチャのレベルゼロに対して記録されるのみである。D3DLOCK_NO_DIRTY_UPDATE または D3DLOCK_READONLY なしで LockRect か LockBox が呼び出されたとき、ダーティーな範囲は自動的に記録される。詳細については、「Direct3DDevice8.UpdateTexture」を参照すること。

参照

Direct3DCubeTexture8.AddDirtyRect、Direct3DCubeTexture8.GetLevelDesc、Direct3DCubeTexture8.UnlockRect


Direct3DCubeTexture8.UnlockRect

キューブ テクスチャ リソース上の矩形をアンロックする。

object.UnlockRect( _
    FaceType As CONST_D3DCUBEMAP_FACES, _
    Level As Long)

指定項目

object
Direct3DCubeTexture8 オブジェクトを表すオブジェクト式。
FaceType
キューブ マップのサーフェスを識別する CONST_D3DCUBEMAP_FACES 列挙のメンバ。
Level
ミップマップ化キューブ テクスチャのレベルを指定する。

エラー コード

失敗した場合はエラーが発生し、Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

参照

Direct3DCubeTexture8.AddDirtyRect、Direct3DCubeTexture8.LockRect


Direct3DDevice8

DrawPrimitive ベースのレンダリング、リソースの作成、システムレベル変数の処理、ガンマ ランプ レベルの調整、およびパレットの処理を行うには、Direct3DDevice8 クラスのメソッドを使用する。

Direct3DDevice8 クラスを取得するには、Direct3D8.CreateDevice メソッドを呼び出す。

Direct3DDevice8 クラスのメソッドは、以下のグループにまとめることができる。

カーソル | SetCursorPosition
 | SetCursorProperties
 | ShowCursor
生成 | CreateAdditionalSwapChain
 | CreateCubeTexture
 | CreateDepthStencilSurface
 | CreateImageSurface
 | CreateIndexBuffer
 | CreateRenderTarget
 | CreateTexture
 | CreateVertexBuffer
 | CreateVolumeTexture
デバイス ステート | ApplyStateBlock
 | BeginStateBlock
 | CaptureStateBlock
 | CreateStateBlock
 | DeleteStateBlock
 | EndStateBlock
 | GetClipStatus
 | GetRenderState
 | GetRenderTarget
 | GetTransform
 | SetClipStatus
 | SetRenderState
 | SetRenderTarget
 | SetTransform
ガンマ ランプ | GetGammaRamp
 | SetGammaRamp
高次プリミティブ | DeletePatch
 | DrawRectPatch
 | DrawTriPatch
インデックス データ | GetIndices
 | SetIndices
情報 | GetAvailableTextureMem
 | GetCreationParameters
 | GetDeviceCaps
 | GetDirect3D
 | GetDisplayMode
 | GetInfo
 | GetRasterStatus
ライティングとマテリアル | GetLight
 | GetLightEnable
 | GetMaterial
 | LightEnable
 | SetLight
 | SetMaterial
その他 | CopyRects
 | MultiplyTransform
 | ProcessVertices
 | ResourceManagerDiscardBytes
 | TestCooperativeLevel
パレット | GetCurrentTexturePalette
 | GetPaletteEntries
 | SetCurrentTexturePalette
 | SetPaletteEntries
ピクセル シェーダ | CreatePixelShader
 | DeletePixelShader
 | GetPixelShader
 | GetPixelShaderConstant
 | GetPixelShaderFunction
 | SetPixelShader
 | SetPixelShaderConstant
プレゼンテーション | Present
 | Reset
レンダリング | DrawIndexedPrimitive
 | DrawIndexedPrimitiveUP
 | DrawPrimitive
 | DrawPrimitiveUP
シーン | BeginScene
 | EndScene
ストリーム データ | GetStreamSource
 | SetStreamSource
サーフェス | GetBackBuffer
 | GetDepthStencilSurface
 | GetFrontBuffer
テクスチャ | GetTexture
 | GetTextureStageState
 | SetTexture
 | SetTextureStageState
 | UpdateTexture
 | ValidateDevice
ユーザー定義クリップ面 | GetClipPlane
 | SetClipPlane
ビューポート | Clear
 | GetViewport
 | SetViewport
頂点シェーダ | CreateVertexShader
 | DeleteVertexShader
 | GetVertexShader
 | GetVertexShaderConstant
 | GetVertexShaderDeclaration
 | GetVertexShaderFunction
 | SetVertexShader
 | SetVertexShaderConstant

参照

Direct3D8.CreateDevice


Direct3DDevice8.ApplyStateBlock

既存のデバイス ステート ブロックをレンダリング デバイスに適用する。

object.ApplyStateBlock( _
    Token As Long)

指定項目

object
Direct3DDevice8 オブジェクトを表すオブジェクト式。
Token
実行するデバイス ステート ブロック （Direct3DDevice8.EndStateBlock メソッドによって返されたデバイス ステート ブロック) のハンドル。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

Token パラメータが無効またはマクロが現在記録中であるとき、Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

値 &hFFFFFFFF& は、無効なステート ブロック ハンドルである。

アプリケーションがほかのブロックを記録している間は、デバイス ステート ブロックを適用できない。

レンダリング デバイスのステートに影響するすべての処理同様、シーンのレンダリング時、つまり Direct3DDevice8.BeginScene メソッドを呼び出してから Direct3DDevice8.EndScene メソッドを呼び出す前に、ステート ブロックを適用することを勧める。

参照

Direct3DDevice8.BeginStateBlock、Direct3DDevice8.EndStateBlock、Direct3DDevice8.CaptureStateBlock、Direct3DDevice8.CreateStateBlock、Direct3DDevice8.DeleteStateBlock


Direct3DDevice8.BeginScene

シーンを開始する。

object.BeginScene()

指定項目

object
Direct3DDevice8 オブジェクトを表すオブジェクト式。

エラー コード

失敗した場合はエラーが発生し、Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

アプリケーションは、レンダリングを実行する前にこのメソッドを呼び出さなければならない。また、レンダリングが完了してから再度 BeginScene を呼び出す前に、Direct3DDevice8.EndScene を呼び出さなければならない。

BeginScene メソッドが失敗すると、デバイスはシーンを開始できないので、Direct3DDevice8.EndScene メソッドを呼び出す必要はない。実際、前の BeginScene の呼び出しが失敗した場合は、EndScene の呼び出しも失敗する。

参照

Direct3DDevice8.EndScene


Direct3DDevice8.BeginStateBlock

Microsoft® Direct3D® にデバイス ステート ブロックの記録を開始するように知らせる。

object.BeginStateBlock()

指定項目

object
Direct3DDevice8 オブジェクトを表すオブジェクト式。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
E_OUTOFMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

アプリケーションは、このメソッドを呼び出す前に、Direct3DDevice8.ValidateDevice メソッドを呼び出して、記録されたすべてのステートが有効かどうかを確認できる。

BeginStateBlock を呼び出してから Direct3DDevice8.EndStateBlock を呼び出すまでにステート ブロックに記録できるメソッドは、次のとおりである。

  • Direct3DDevice8.LightEnable
  • Direct3DDevice8.SetClipPlane
  • Direct3DDevice8.SetIndices
  • Direct3DDevice8.SetLight
  • Direct3DDevice8.SetMaterial
  • Direct3DDevice8.SetPixelShader
  • Direct3DDevice8.SetPixelShaderConstant
  • Direct3DDevice8.SetRenderState
  • Direct3DDevice8.SetStreamSource
  • Direct3DDevice8.SetTexture
  • Direct3DDevice8.SetTextureStageState
  • Direct3DDevice8.SetTransform
  • Direct3DDevice8.SetViewport
  • Direct3DDevice8.SetVertexShader
  • Direct3DDevice8.SetVertexShaderConstant

ステート ブロックでのステート変化の順序は保証されない。ステート ブロックで同じステートが複数回指定された場合、使用されるのは最後の値のみである。

参照

Direct3DDevice8.ApplyStateBlock、Direct3DDevice8.EndStateBlock、Direct3DDevice8.CaptureStateBlock、Direct3DDevice8.CreateStateBlock、Direct3DDevice8.DeleteStateBlock


Direct3DDevice8.CaptureStateBlock

既存のステート ブロック内の値を、デバイスに設定されている値に更新する。

object.CaptureStateBlock( _
    Token As Long)

指定項目

object
Direct3DDevice8 オブジェクトを表すオブジェクト式。
Token
デバイス ステートを取り込むステート ブロックへのハンドル。

エラー コード

失敗した場合はエラーが発生し、Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

値 &hFFFFFFFF& は、無効なステート ブロック ハンドルである。

このメソッドは、既存のステート ブロックに、更新されたステートの値をキャプチャする。デバイスのステート全体をキャプチャするのではない。

CaptureStateBlock は、ステートブロックの作成後に、明示的または非明示的に作成されたライトの情報を取り込まない。たとえば、現在のステートを D3DSBT_ALL 型のステートブロックに取り込んでも、取り込み後に作成されたライトの情報は保存されない。

参照

Direct3DDevice8.ApplyStateBlock、Direct3DDevice8.BeginStateBlock、Direct3DDevice8.CreateStateBlock、Direct3DDevice8.EndStateBlock、Direct3DDevice8.DeleteStateBlock


Direct3DDevice8.Clear

ビューポートまたはビューポート内の矩形セットを指定された RGBA 色にクリアし、深度バッファをクリアし、ステンシル バッファを削除する。

object.Clear( _
    Count As Long, _
    ClearD3DRect As Any,
    Flags As CONST_D3DCLEARFLAGS, _
    Color As Long, _
    Z As Single, _
    Stencil As Long)

指定項目

object
Direct3DDevice8 オブジェクトを表すオブジェクト式。
Count
ClearD3DRect の配列にある矩形の数。ClearD3DRect を ByVal 0 に設定した場合、このパラメータは 0 に設定しなければならない。
ClearD3DRect
クリアする矩形が記述されている D3DRECT 型配列の最初の要素。矩形をレンダリング ターゲットのディメンジョンに設定すると、サーフェス全体がクリアされる。各矩形は、レンダリング ターゲット サーフェス上のポイントに対応するスクリーン座標を使用する。座標はビューポートの矩形の境界でクリップされる。このパラメータを ByVal 0 に設定すると、ビューポート矩形全体がクリアされる。
Flags
クリアするサーフェスを示す、CONST_D3DCLEARFLAGS 列挙で定義されたフラグの組み合わせ。少なくとも 1 つのフラグを使用しなければならない。
Color
レンダリング ターゲット サーフェスのクリアに使用する 32 ビットの ARGB カラー値。
Z
このメソッドが深度バッファに保存する新しい z 値。このパラメータには 0.0 から 1.0 までの値を使用できる (Z ベースまたは W ベースの深度バッファの場合)。0.0 はビューアに最も近い距離、1.0 は最も遠い距離を表す。
Stencil
各ステンシル バッファのエントリに保存する整数値。このパラメータには 0 から 2n-1 までの値を使用できる。n はステンシル バッファのビット深度。

エラー コード

失敗した場合はエラーが発生し、Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

レンダリング ターゲットに深度バッファがアタッチされていないときに D3DCLEAR_ZBUFFER フラグまたは D3DCLEAR_STENCIL フラグを指定すると、このメソッドは失敗する。同様に、深度バッファ フォーマットにステンシル バッファ情報が含まれていない場合に D3DCLEAR_STENCIL フラグを指定すると、このメソッドは失敗する。

以下に示すコードは、Clear をデフォルトの指定で呼び出す方法である。

Dim Device As Direct3DDevice8

' Flags、Color、Z、および Stencil には
' 有効な値が設定されていると仮定する。
Device.Clear 0, ByVal 0, Flags, Color, Z, Stencil

次のコードは、クリアする矩形の配列を指定して Clear を呼び出す方法を示している。

Dim clearD3dRects(10)
device.Clear 10, clearD3dRects(0), Flags, Color, Z, Stencil

クリアする矩形の配列の先頭要素だけを渡すことに注意すること。


Direct3DDevice8.CopyRects

あるサーフェスから別のサーフェスに、ピクセルの矩形サブセットをコピーする。

object.CopyRects( _
    SourceSurface As Direct3DSurface8, _
    FirstElementOfSourceRectsArray As Any, _
    NumberOfRects As Long, _
    DestinationSurface As Direct3DSurface8, _
    FirstElementofDestPointArray As Any)

指定項目

object
Direct3DDevice8 オブジェクトを表すオブジェクト式。
SourceSurface
コピー元のサーフェスを表す Direct3DSurface8 オブジェクト。このパラメータでは、DestinationSurface と異なるサーフェス オブジェクトを指定しなければならない。
FirstElementOfSourceRectsArray
転送される矩形を表す配列の最初の要素、またはサーフェス全体のコピーを指定する ByVal 0。各矩形はコピー先のサーフェスに転送されて、矩形の左上隅は FirstElementofDestPointArray の対応する要素で示されている位置になる。
NumberOfRects
FirstElementOfSourceRectsArray に含まれる矩形の数。
DestinationSurface
コピー先のサーフェスを表す Direct3DSurface8 オブジェクト。このパラメータでは、SourceSurface と異なるサーフェス オブジェクトを指定しなければならない。
FirstElementofDestPointArray
一連のポイントを定義している配列の先頭の要素。FirstElementOfSourceRectsArray に格納されている各矩形の左上隅の位置を示す。このパラメータが ByVal 0 の場合、矩形はコピー元の矩形と同じオフセット (左上隅の位置が同じ) にコピーされる。

エラー コード

失敗した場合はエラーが発生し、Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

このメソッドは、伸縮、カラー キー、アルファ ブレンド、フォーマット変換、および転送元または転送先矩形のいずれかのクリッピングをサポートしていない。すべての転送元矩形および対応する転送先矩形が、それぞれ転送元および転送先サーフェス内に完全に含まれていない場合には、このメソッドが失敗することに注意する。2 つのサーフェスのフォーマットは一致していなければならないが、ディメンジョンは異なっていてもかまわない。

サーフェスのフォーマットが深度ステンシル フォーマットの場合、このメソッドは適用できない。

宛先サーフェスがテクスチャのレベルゼロなら、それはダーティーとマークされる。詳細については、「IDirect3DDevice8.UpdateTexture」および「IDirect3DTexture8.AddDirtyRect」を参照すること。


Direct3DDevice8.CreateAdditionalSwapChain

複数のビューをレンダリングするための追加スワップ チェーンを作成する。

object.CreateAdditionalSwapChain( _
    PresentationParameters As D3DPRESENT_PARAMETERS) As Direct3DSwapChain8

指定項目

object
Direct3DDevice8 オブジェクトを表すオブジェクト式。
PresentationParameters
新しいスワップ チェーンのプレゼンテーション パラメータを表す D3DPRESENT_PARAMETERS 型。

戻り値

追加スワップ チェーンを表す Direct3DSwapChain8 オブジェクト。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DERR_OUTOFVIDEOMEMORY
E_OUTOFMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

Microsoft® Direct3D® for Microsoft DirectX 8.0® はデバイスのプロパティとして 1 つのスワップ チェーンを持っているため、各デバイスに対して、常に少なくても 1 つのスワップ チェーンが存在する。

どのようなデバイスでも、サポートできるフルスクリーン スワップ チェーンは 1 つだけである。

参照

ウィンドウ モードのマルチビュー


Direct3DDevice8.CreateCubeTexture

キューブ テクスチャ リソースを作成する。

object.CreateCubeTexture( _
    EdgeLength As Long, _
    Levels As Long, _
    Usage As Long, _
    Format As CONST_D3DFORMAT, _
    Pool As CONST_D3DPOOL) As Direct3DCubeTexture8

指定項目

object
Direct3DDevice8 オブジェクトを表すオブジェクト式。
EdgeLength
キューブ テクスチャのすべての最上位サーフェスのエッジのサイズ。各サーフェスのミップマップ レベルが下のピクセル ディメンジョンは 1 つ上のレベルのピクセル ディメンジョンを (単純に) 半分にした値である。それぞれの大きさは、1 ピクセルのサイズに収められる。2 で除算した結果が 0 の場合、代わりに 1 が使用される。
Levels
キューブ テクスチャの各サーフェスのレベルの数。0 (ゼロ) を指定すると、Microsoft® Direct3D® は、ミップマップ化キューブ テクスチャをサポートするハードウェアに対して、各面の 1 × 1 ピクセルまでのすべてのキューブ テクスチャ サブレベルを生成する。その他の値を指定した場合は、1 レベルを生成する。Direct3DBaseTexture8.GetLevelCount を呼び出して、生成されたレベル数を確認する。
Usage
このリソースの使用方法を記述する CONST_D3DUSAGEFLAGS 列挙で定義される次の 1 つ以上のフラグの組み合わせ。
D3DUSAGE_DEPTHSTENCIL
サーフェスが深度ステンシル サーフェスとして使用されることを示す。リソースは、Direct3DDevice8.SetRenderTarget メソッドの NewDepthStencil パラメータに渡すことができる。「注意」を参照すること。
D3DUSAGE_RENDERTARGET
サーフェスがレンダリング ターゲットとして使用されることを示す。リソースは、SetRenderTarget メソッドの NewRenderTarget パラメータに渡すことができる。「注意」を参照すること。

D3DUSAGE_RENDERTARGET または D3DUSAGE_DEPTHSTENCIL のいずれかが指定された場合は、アプリケーションで Direct3D8.CheckDeviceFormat を呼び出して、デバイスがこれらの処理をサポートするかどうかを確認しなければならない。

Format
CONST_D3DFORMAT 列挙のメンバ。キューブ テクスチャの全サーフェスの全レベルのフォーマットを示す。
Pool
CONST_D3DPOOL 列挙のメンバ。キューブ テクスチャを格納するメモリ クラスを示す。

戻り値

作成されたキューブ テクスチャ リソースを表す Direct3DCubeTexture8 オブジェクト。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DERR_OUTOFVIDEOMEMORY
E_OUTOFMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

キューブ テクスチャは、サーフェスの集合であるポイントがほかのサーフェスと異なる。キューブ テクスチャを指定して SetRenderTarget を呼び出すには、Direct3DCubeTexture8.GetCubeMapSurface を使って個別のサーフェスを選択してから、それを SetRenderTarget に渡さなければならない。

テクスチャ (ミップマップ) は、連続してダウンサンプリングされた (ミップマップ化された) サーフェスの集合である。一方、CreateCubeTexture で作成されるキューブ テクスチャは、サーフェスごとに 1 つずつ、全部で 6 つのテクスチャ (ミップマップ) の集合である。すべてのサーフェスは、キューブ テクスチャに存在していなければならない。また、キューブ マップ サーフェスは、3 つのディメンジョン (x、y、および z) がすべて同じピクセル サイズでなければならない。

DirectX 8.0 では、リソースの使用が強制される。特定の処理においてリソースを使おうとするアプリケーションは、リソースの作成時に目的の処理を指定する必要がある。


Direct3DDevice8.CreateDepthStencilSurface

深度ステンシル リソースを作成する。

object.CreateDepthStencilSurface( _
    Width As Long, _
    Height As Long, _
    Format As CONST_D3DFORMAT, _
    MultiSample As CONST_D3DMULTISAMPLE_TYPE, _
    Surface As Direct3DSurface8)

指定項目

object
Direct3DDevice8 オブジェクトを表すオブジェクト式。
Width
深度ステンシル サーフェスの幅 (ピクセル単位)。
Height
深度ステンシル サーフェスの高さ (ピクセル単位)。
Format
深度ステンシル サーフェスのフォーマットを示す CONST_D3DFORMAT 列挙のメンバ。この値は、そのデバイスに対して列挙された深度ステンシル フォーマットの 1 つでなければならない。
MultiSample
マルチサンプリング バッファ タイプを示す CONST_D3DMULTISAMPLE_TYPE 列挙のメンバ。この値は、使用できるマルチサンプリング タイプの 1 つでなければならない。このサーフェスを SetRenderTarget に渡すときは、マルチサンプリング タイプがレンダリング ターゲットのものと同じでなければならない。
Surface
作成された深度ステンシル サーフェス リソースを表す Direct3DSurface8 オブジェクト。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DERR_OUTOFVIDEOMEMORY
E_OUTOFMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

深度ステンシル バッファのメモリ クラスは、常に D3DPOOL_DEFAULT である。

参照

Direct3DDevice8.CopyRects、Direct3DDevice8.SetRenderTarget


Direct3DDevice8.CreateImageSurface

イメージ サーフェスを作成する。

object.CreateImageSurface( _
    Width As Long, _
    Height As Long, _
    Format As CONST_D3DFORMAT) As Direct3DSurface8

指定項目

object
Direct3DDevice8 オブジェクトを表すオブジェクト式。
Width
イメージ サーフェスの幅 (ピクセル単位)。
Height
イメージ サーフェスの高さ (ピクセル単位)。
Format
イメージ サーフェスのフォーマットを示す CONST_D3DFORMAT 列挙型のメンバ。

戻り値

作成されたイメージ サーフェスを表す Direct3DSurface8 オブジェクト。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DERR_OUTOFVIDEOMEMORY
E_OUTOFMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

イメージ サーフェスはプレース ホルダであり、ロック処理と Direct3DDevice8.CopyRects を除くすべての Microsoft® Direct3D® 操作で使用できない。

イメージ サーフェスは、D3DPOOL_SYSTEMMEM メモリ クラスに格納される。


Direct3DDevice8.CreateIndexBuffer

インデックス バッファを作成する。

object.CreateIndexBuffer( _
    LengthInBytes As Long, _
    Usage As Long, _
    Format As CONST_D3DFORMAT, _
    Pool As CONST_D3DPOOL) As Direct3DIndexBuffer8

指定項目

object
Direct3DDevice8 オブジェクトを表すオブジェクト式。
LengthInBytes
インデックス バッファのサイズ (バイト単位)。
Usage
このリソースの使用方法の制御情報を記述する。CONST_D3DUSAGEFLAGS 列挙で定義される次の 1 つ以上のフラグの組み合わせ。
D3DUSAGE_DONOTCLIP
インデックス バッファの内容が決してクリッピングを要求しないことを示す。
D3DUSAGE_DYNAMIC
頂点またはインデックス バッファが動的なメモリの使用を必要とすることを示す。この使用方法は、ドライバが配置する場所を決定できるので、ドライバにとって有効である。一般的に、静的な頂点バッファはビデオ メモリに配置され、動的な頂点バッファは AGP メモリに配置される。分割した静的な使用方法は存在しないことに注意すること。D3DUSAGE_DYNAMIC を指定しない場合に、頂点バッファは静的に作成される。D3DUSAGE_DYNAMIC は、D3DLOCK_DISCARD および D3DLOCK_NOOVERWRITE ロッキング フラグによって厳密に強制される。この結果、D3DLOCK_DISCARD および D3DLOCK_NOOVERWRITE は、D3DUSAGE_DYNAMIC を指定して作成された頂点およびインデックス バッファでのみ有効である。これらは、静的な頂点バッファでは有効なフラグではない。

D3DUSAGE_DYNAMIC は、管理下の頂点およびインデックス バッファでは指定できないことに注意すること。詳細については、「リソースの管理」を参照すること。

D3DUSAGE_RTPATCHES
高次プリミティブの描画にインデックス バッファを使用するとき設定する。
D3DUSAGE_NPATCHES
N パッチの描画にインデックス バッファを使用するとき設定する。
D3DUSAGE_POINTS
ポイント スプライトまたはインデックス付きポイント リストの描画に、インデックス バッファを使用するとき設定する。
D3DUSAGE_SOFTWAREPROCESSING
バッファがソフトウェア処理で使用されることを示す。
D3DUSAGE_WRITEONLY
インデックス バッファへの書き込み操作しか実行できないことをシステムに通知する。このフラグを使用すると、ドライバは最適なメモリ領域を選択して効率的に書き込み操作やレンダリングを実行できる。この能力を使用して作成されたインデックス バッファからの読み込みを試みると、パフォーマンスが低下する場合がある。
Format
インデックス バッファのフォーマットを示す CONST_D3DFORMAT 列挙のメンバ。有効な設定は次のとおりである。
D3DFMT_INDEX16
インデックスはそれぞれ 16 ビットである。
D3DFMT_INDEX32
インデックスはそれぞれ 32 ビットである。「注意」を参照すること。
Pool
CONST_D3DPOOL 列挙のメンバ。リソースが配置される有効なメモリ クラスを記述する。

戻り値

作成されたインデックス バッファ リソースを表す Direct3DIndexBuffer8 オブジェクト。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DERR_OUTOFVIDEOMEMORY
D3DXERR_INVALIDDATA
E_OUTOFMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

インデックス バッファは、インデックスを保持するために使われるメモリ リソースであり、サーフェス バッファおよび頂点バッファに似ている。インデックス バッファを使うことで、Microsoft® Direct3D® では、データの不必要なコピー処理を避けることができ、意図されている使用方法に最適なメモリ タイプにバッファを格納することができる。

インデックス バッファを使うには、インデックス バッファを作成し、それをロックして、インデックスを格納する。次に、バッファをアンロックし、Direct3DDevice8.SetIndices に渡して頂点と頂点シェーダを設定し、Direct3DDevice8.DrawIndexedPrimitive を呼び出してレンダリングを行う。

D3DCAPS8 型の MaxVertexIndex メンバは、レンダリングで有効なインデックス バッファのタイプを示す。

参照

Direct3DIndexBuffer8.GetDesc


Direct3DDevice8.CreatePixelShader

ピクセル シェーダを作成する。

object.CreatePixelShader( _
    FunctionTokenArray As Long) As Long

指定項目

object
Direct3DDevice8 オブジェクトを表すオブジェクト式。
FunctionTokenArray
ブレンディング処理を指定するピクセル シェーダ関数のトークン配列の先頭要素。

戻り値

ピクセル シェーダのハンドル。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DERR_OUTOFVIDEOMEMORY
E_OUTOFMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

参照

Direct3DDevice8.DeletePixelShader、D3DX8.AssembleShader、D3DX8.AssembleShaderFromFile


Direct3DDevice8.CreateRenderTarget

レンダリング ターゲット サーフェスを作成する。

object.CreateRenderTarget( _
    Width As Long, _
    Height As Long, _
    Format As CONST_D3DFORMAT, _
    MultiSample As CONST_D3DMULTISAMPLE_TYPE, _
    Lockable As Long) As Direct3DSurface8

指定項目

object
Direct3DDevice8 オブジェクトを表すオブジェクト式。
Width
レンダリング ターゲット サーフェスの幅 (ピクセル単位)。
Height
レンダリング ターゲット サーフェスの高さ (ピクセル単位)。
Format
レンダリング ターゲットのフォーマットを示す CONST_D3DFORMAT 列挙のメンバ。
MultiSample
マルチサンプリング バッファ タイプを示す CONST_D3DMULTISAMPLE_TYPE 列挙のメンバ。このパラメータでは、作成するレンダリング ターゲットのアンチエイリアシング タイプを指定する。このタイプは、両方のバッファを SetRenderTarget に渡すときの深度ステンシル バッファのものと同じでなければならない。
Lockable
レンダリング ターゲット サーフェスがロック可能かどうかを指定する値。TRUE に設定されている場合、レンダリング ターゲットはロックできる。FALSE に設定されている場合、レンダリング ターゲットはロックできない。ロック可能なレンダリング ターゲットによって、一部のグラフィック ハードウェアではパフォーマンスのコストが増すことに注意すること。

戻り値

レンダリング ターゲット サーフェスを表す Direct3DSurface8 オブジェクト。

注意

レンダリング ターゲット サーフェスは、D3DPOOL_DEFAULT メモリ クラスに格納される。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DERR_OUTOFVIDEOMEMORY
E_OUTOFMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。


Direct3DDevice8.CreateStateBlock

すべてのデバイス ステート、頂点関連のステート、またはピクセル関連のステートの値を含む新しいステート ブロックを作成する。

object.CreateStateBlock( _
    BlockType As CONST_D3DSTATEBLOCKTYPE) As Long

指定項目

object
Direct3DDevice8 オブジェクトを表すオブジェクト式。
BlockType
メソッドによってキャプチャされるステート データの型。CONST_D3DSTATEBLOCKTYPE 列挙で定義されている値を設定できる。

戻り値

メソッドが成功した場合は、ステート ブロック ハンドルを含む Long 値。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DERR_OUTOFVIDEOMEMORY
E_OUTOFMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

値 &hFFFFFFFF& は、無効なステート ブロック ハンドルである。

頂点関連のデバイス ステートとは、一般には、システムによる頂点の処理方法に影響するステートをいう。ピクセル関連のステートとは、通常、ラスタ化の際のシステムによるピクセルまたは深度バッファの処理方法に影響するデバイス ステートのことである。一部のステートは両方のグループに属する。

参照

Direct3DDevice8.ApplyStateBlock、Direct3DDevice8.BeginStateBlock、Direct3DDevice8.CaptureStateBlock、Direct3DDevice8.EndStateBlock、Direct3DDevice8.DeleteStateBlock


Direct3DDevice8.CreateTexture

テクスチャ リソースを作成する。

object.CreateTexture( _
    Width As Long, _
    Height As Long, _
    Levels As Long, _
    Usage As Long, _
    Format As CONST_D3DFORMAT, _
    Pool As CONST_D3DPOOL) As Direct3DTexture8

指定項目

object
Direct3DDevice8 オブジェクトを表すオブジェクト式。
Width
テクスチャの最上位レベルの幅 (ピクセル単位)。各サーフェスのミップマップ レベルが下のピクセル ディメンジョンは 1 つ上のレベルのピクセル ディメンジョンを (単純に) 半分にした値である。それぞれの大きさは、1 ピクセルのサイズに収められる。2 で除算した結果が 0 の場合、代わりに 1 が使用される。
Height
テクスチャの最上位レベルの高さ (ピクセル単位)。各サーフェスのミップマップ レベルが下のピクセル ディメンジョンは 1 つ上のレベルのピクセル ディメンジョンを (単純に) 半分にした値である。それぞれの大きさは、1 ピクセルのサイズに収められる。2 で除算した結果が 0 の場合、代わりに 1 が使用される。
Levels
テクスチャのレベルの数。0 (ゼロ) を指定すると、Microsoft® Direct3D® は、ミップマップ化テクスチャをサポートするハードウェアに対し、1 × 1 ピクセルまでのすべてのテクスチャ サブレベルを生成する。その他の値を指定した場合は、1 レベルを生成する。Direct3DBaseTexture8.GetLevelCount を呼び出して、生成されたレベル数を確認する。
Usage
このリソースの使用方法を記述する CONST_D3DUSAGEFLAGS 列挙で定義される次の 1 つ以上のフラグの組み合わせ。
D3DUSAGE_DEPTHSTENCIL
サーフェスが深度ステンシル サーフェスとして使用されることを示す。リソースは、Direct3DDevice8.SetRenderTarget メソッドの NewDepthStencil パラメータに渡すことができる。
D3DUSAGE_RENDERTARGET
サーフェスがレンダリング ターゲットとして使用されることを示す。リソースは、SetRenderTarget メソッドの NewRenderTarget パラメータに渡すことができる。

D3DUSAGE_RENDERTARGET または D3DUSAGE_DEPTHSTENCIL のいずれかが指定された場合は、アプリケーションで Direct3D8.CheckDeviceFormat を呼び出して、デバイスがこれらの処理をサポートするかどうかを確認しなければならない。

Format
テクスチャの全レベルのフォーマットを示す CONST_D3DFORMAT 列挙のメンバ。
Pool
テクスチャを格納するメモリ クラスを示す CONST_D3DPOOL 列挙のメンバ。

戻り値

作成されたテクスチャ リソースを表す Direct3DTexture8 オブジェクト。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DERR_OUTOFVIDEOMEMORY
E_OUTOFMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

テクスチャを指定して Direct3DDevice8.SetRenderTarget を呼び出すには、Direct3DTexture8.GetSurfaceLevel を使ってレベルを選択し、選択したサーフェスを SetRenderTarget に渡さなければならない。


Direct3DDevice8.CreateVertexBuffer

頂点バッファを作成する。

object.CreateVertexBuffer( _
    LengthInBytes As Long, _
    Usage As Long, _
    FVF As Long, _
    Pool As CONST_D3DPOOL) As Direct3DVertexBuffer8

指定項目

object
Direct3DDevice8 オブジェクトを表すオブジェクト式。
LengthInBytes
頂点バッファのサイズ (バイト単位)。柔軟な頂点フォーマット (FVF) バッファの場合は、Length は少なくとも 1 つの頂点を格納できる大きさでなければならないが、頂点サイズの倍数である必要はない。Length は FVF バッファについてのみ検証される。
Usage
このリソースの使用方法の制御情報を記述する。CONST_D3DUSAGEFLAGS 列挙で定義される次の 1 つ以上のフラグの組み合わせ。
D3DUSAGE_DONOTCLIP
頂点バッファの内容が決してクリッピングを要求しないことを示す。このフラグが設定されたバッファを使ってレンダリングする場合は、D3DRS_CLIPPING レンダリング ステートが FALSE に設定されていなければならない。
D3DUSAGE_DYNAMIC
頂点またはインデックス バッファが動的なメモリの使用を必要とすることを示す。この使用方法は、ドライバが配置する場所を決定できるので、ドライバにとって有効である。一般的に、静的な頂点バッファはビデオ メモリに配置され、動的な頂点バッファは AGP メモリに配置される。分割した静的な使用方法は存在しないことに注意すること。D3DUSAGE_DYNAMIC を指定しない場合に、頂点バッファは静的に作成される。D3DUSAGE_DYNAMIC は、D3DLOCK_DISCARD および D3DLOCK_NOOVERWRITE ロッキング フラグによって厳密に強制される。この結果、D3DLOCK_DISCARD および D3DLOCK_NOOVERWRITE は、D3DUSAGE_DYNAMIC を指定して作成された頂点およびインデックス バッファでのみ有効である。これらは、静的な頂点バッファでは有効なフラグではない。

動的な頂点バッファの使用の詳細については、「動的な頂点およびインデックス バッファの使い方」を参照すること。

D3DUSAGE_DYNAMIC は、管理下の頂点およびインデックス バッファでは指定できないことに注意すること。詳細については、「リソースの管理」を参照すること。

D3DUSAGE_RTPATCHES
高次プリミティブの描画に頂点バッファを使用するとき設定する。
D3DUSAGE_NPATCHES
N パッチの描画に頂点バッファを使用するとき設定する。
D3DUSAGE_POINTS
ポイント スプライトまたはインデックス付きポイント リストの描画に、頂点バッファを使用するとき設定する。
D3DUSAGE_SOFTWAREPROCESSING
ソフトウェア頂点処理で使用する頂点バッファであることを示す。
D3DUSAGE_WRITEONLY
頂点バッファへの書き込み操作しか実行できないことをシステムに知らせる。このフラグを使用することにより、ドライバは最適なメモリ領域を選択して効率的に書き込み操作やレンダリングを実行する。この能力を使用して作成された頂点バッファからの読み出しは失敗する。
FVF
柔軟な頂点フォーマット フラグの組み合わせ。バッファ内の頂点の頂点フォーマットを記述する使用方法の指定子。このパラメータを有効な FVF コードに設定すると、作成される頂点バッファは FVF 頂点バッファになる (「注意」を参照)。このパラメータを 0 (ゼロ) に設定すると、頂点バッファは非 FVF 頂点バッファになる。
Pool
CONST_D3DPOOL 列挙のメンバ。リソースが配置される有効なメモリ クラスを記述する。

戻り値

作成された頂点バッファ リソースを表す Direct3DVertexBuffer8 オブジェクト。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DERR_OUTOFVIDEOMEMORY
E_OUTOFMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

Direct3DDevice8 クラスは、頂点バッファ オブジェクトに格納された頂点データを使用するプリミティブのレンダリングをサポートしている。頂点バッファは Direct3DDevice8 クラスから作成されて、頂点バッファの基になっている Direct3DDevice8 オブジェクトでのみ使用できる。

FVF パラメータにゼロ以外の値を設定するときは、有効な FVF コードでなければならず、これはバッファの内容が FVF コードによって特徴付けられることを示している。FVF コードで作成された頂点バッファは、FVF 頂点バッファと呼ばれる。詳細については、「FVF 頂点バッファ」を参照すること。

D3DUSAGE_SOFTWAREPROCESSING フラグは、頂点バッファがソフトウェア頂点処理で使われるものであることを示している。詳細については、「デバイスの種類と頂点処理の要件」を参照すること。

非 FVF バッファを使用して、マルチパス レンダリングまたはシングル パスのマルチテクスチャ レンダリングで、データをインターリーブすることができる。これを行うには、1 つのバッファにはジオメトリ データを格納し、もう 1 つのバッファにはレンダリングする各テクスチャのテクスチャ座標データを格納する。レンダリング時には、テクスチャ座標を格納する各バッファと共に、ジオメトリ データを格納するバッファがインターリーブされる。代わりに FVF バッファを使用した場合、各バッファに、レンダリングする各テクスチャに固有のテクスチャ座標データに加えて、同じジオメトリ データを格納する必要がある。これは、使用するストラテジにもよるが、スピードまたはメモリの面でマイナスとなる。テクスチャ座標の詳細については、「テクスチャ座標について」を参照すること。

参照

Direct3DVertexBuffer8.GetDesc、Direct3DDevice8.ProcessVertices


Direct3DDevice8.CreateVertexShader

頂点シェーダを作成し、作成が成功した場合は、そのシェーダをカレント シェーダとして設定する。

object.CreateVertexShader( _
    DeclarationTokenArray As Long, _
    FunctionTokenArray As Any, _
    retHandle As Long, _
    Usage As Long)

指定項目

object
Direct3DDevice8 オブジェクトを表すオブジェクト式。
DeclarationTokenArray
頂点シェーダの宣言トークン配列の先頭要素。このパラメータではシェーダへの入力を定義し、入力データ ストリーム中の頂点要素のシェーダによる使用方法も指定する。
FunctionTokenArray
頂点シェーダの機能トークン配列の先頭要素。このパラメータでは、各頂点に適用する処理を定義する。このパラメータを ByVal 0 にすると、固定機能パイプライン用のシェーダが作成される。DeclarationTokenArray で示されているパラメータ宣言が現在の宣言になり、その後の Direct3DDevice8.SetVertexShader の呼び出しで設定できる。

このパラメータに ByVal 0 以外の値を設定すると、シェーダはプログラム可能になる。

retHandle
返される頂点シェーダのハンドル。
Usage
頂点シェーダに対する使用方法の制御情報。次のフラグを設定できる。
D3DUSAGE_SOFTWAREPROCESSING
ソフトウェア頂点処理で使用する頂点シェーダであることを示す。CONST_D3DRENDERSTATETYPE 列挙型の D3DRS_SOFTWAREVERTEXPROCESSING メンバが TRUE のときに使用する頂点シェーダに対しては D3DUSAGE_SOFTWAREPROCESSING フラグを設定しなければならず、D3DRS_SOFTWAREVERTEXPROCESSING が FALSE のときの頂点シェーダに対してはこのフラグを設定してはならない。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DERR_OUTOFVIDEOMEMORY
E_OUTOFMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

頂点シェーダは、シェーダの宣言と機能を指定する 2 つのトークン配列によって定義される。トークン配列は、1 つ以上の Long トークンで構成されており、配列の末尾は特殊なトークン値 &HFFFFFFFF で示される。

シェーダの宣言はシェーダの静的な外部インターフェイスを定義しており、頂点レジスタ入力に対するストリーム データのバインドや、シェーダの定数メモリにロードされる値などが含まれる。シェーダの機能では、シェーダがデバイスにバインドされている間に各頂点に対する処理のために実行される命令の配列として、シェーダの動作が定義されている。機能の配列を指定しないでシェーダを作成すると、そのシェーダがカレント シェーダのときには、固定機能の頂点処理が適用される。

宣言のトークン配列を生成するために使用する定数の定義については、d3dshader.bas を参照すること。

参照

Direct3DDevice8.DeleteVertexShader、D3DX8.AssembleShader、D3DX8.AssembleShaderFromFile、D3DX8.DeclaratorFromFVF


Direct3DDevice8.CreateVolumeTexture

ボリューム テクスチャ リソースを作成する。

object.CreateVolumeTexture( _
    Width As Long, _
    Height As Long, _
    Depth As Long, _
    Levels As Long, _
    Usage As Long, _
    Format As CONST_D3DFORMAT, _
    Pool As CONST_D3DPOOL) As Direct3DVolumeTexture8

指定項目

object
Direct3DDevice8 オブジェクトを表すオブジェクト式。
Width
ボリューム テクスチャの最上位レベルの幅 (ピクセル単位)。この値は 2 の累乗でなければならない。ミップマップ レベルが下のピクセル ディメンジョンは 1 つ上のレベルのピクセル ディメンジョンを (単純に) 半分にした値である。それぞれの大きさは、1 ピクセルのサイズに収められる。したがって、2 で除算した結果が 0 の場合、代わりに 1 が使用される。
Height
ボリューム テクスチャの最上位レベルの高さ (ピクセル単位)。この値は 2 の累乗でなければならない。ミップマップ レベルが下のピクセル ディメンジョンは 1 つ上のレベルのピクセル ディメンジョンを (単純に) 半分にした値である。それぞれの大きさは、1 ピクセルのサイズに収められる。したがって、2 で除算した結果が 0 の場合、代わりに 1 が使用される。
Depth
ボリューム テクスチャの最上位レベルの深度 (ピクセル単位)。この値は 2 の累乗でなければならない。ミップマップ レベルが下のピクセル ディメンジョンは 1 つ上のレベルのピクセル ディメンジョンを (単純に) 半分にした値である。それぞれの大きさは、1 ピクセルのサイズに収められる。したがって、2 で除算した結果が 0 の場合、代わりに 1 が使用される。
Levels
ボリューム テクスチャのレベルの数。0 (ゼロ) を指定すると、Microsoft® Direct3D® は、ミップマップ化ボリューム テクスチャをサポートするハードウェアに対し、1 × 1 × 1 ピクセルまでのすべてのテクスチャ サブレベルを生成する。その他の値を指定した場合は、1 レベルを生成する。Direct3DBaseTexture8.GetLevelCount を呼び出して、生成されるレベル数を確認する。
Usage
現在は使用されていない。0 に設定される。
Format
ボリューム テクスチャの全レベルのフォーマットを示す CONST_D3DFORMAT 列挙のメンバ。
Pool
ボリューム テクスチャを格納するメモリ クラスを示す CONST_D3DPOOL 列挙のメンバ。

戻り値

作成されたボリューム テクスチャ リソースを表す Direct3DVolumeTexture8 オブジェクト。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DERR_OUTOFVIDEOMEMORY
E_OUTOFMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。


Direct3DDevice8.DeletePatch

キャッシュされていた高次パッチを解放する。

object.DeletePatch( _
    Handle As Long)

指定項目

object
Direct3DDevice8 オブジェクトを表すオブジェクト式。
Handle
削除するキャッシュされていた高次パッチのハンドル。

エラー コード

失敗した場合はエラーが発生し、Err.Number に D3DERR_INVALIDPARAMS が設定されて、Handle パラメータが無効であるか、または現在マクロを記録中であることが示される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

参照

Direct3DDevice8.DrawRectPatch、Direct3DDevice8.DrawTriPatch、パッチの描画


Direct3DDevice8.DeletePixelShader

指定されたハンドルで参照されているピクセル シェーダを削除する。

object.DeletePixelShader( _
    PixelShaderHandle As Long)

指定項目

object
Direct3DDevice8 オブジェクトを表すオブジェクト式。
PixelShaderHandle
内部エントリから削除するピクセル シェーダを示すピクセル シェーダ ハンドル。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DERR_OUTOFVIDEOMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

参照

Direct3DDevice8.CreatePixelShader


Direct3DDevice8.DeleteStateBlock

記録されているデバイス ステート ブロックを削除する。

object.DeleteStateBlock( _
    Token As Long)

指定項目

object
Direct3DDevice8 オブジェクトを表すオブジェクト式。
Token
削除するデバイス ステート ブロック （Direct3DDevice8.EndStateBlock メソッドによって返されたデバイス ステート ブロック) のハンドル。

エラー コード

失敗した場合はエラーが発生し、Err.Number に D3DERR_INVALIDCALL が設定される。

D3DERR_INVALIDCALL
D3DERR_OUTOFVIDEOMEMORY

Token パラメータが無効またはマクロが現在記録中であるとき、Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

値 &hFFFFFFFF& は、無効なステート ブロック ハンドルである。

別のステート ブロックの記録中に、デバイス ステート ブロックを削除することはできない。

参照

Direct3DDevice8.ApplyStateBlock、Direct3DDevice8.BeginStateBlock、Direct3DDevice8.CaptureStateBlock、Direct3DDevice8.CreateStateBlock、Direct3DDevice8.EndStateBlock


Direct3DDevice8.DeleteVertexShader

指定されたハンドルで参照されている頂点シェーダを削除し、関連するリソースを解放する。

object.DeleteVertexShader( _
    VertexShaderHandle As Long)

指定項目

object
Direct3DDevice8 オブジェクトを表すオブジェクト式。
VertexShaderHandle
削除する頂点シェーダを示す頂点シェーダ ハンドル。

エラー コード

失敗した場合はエラーが発生し、Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

参照

Direct3DDevice8.CreateVertexShader


Direct3DDevice8.DrawIndexedPrimitive

頂点の配列へのインデックスに基づいて、指定されたジオメトリ プリミティブをレンダリングする。

object.DrawIndexedPrimitive( _
    PrimitiveType As CONST_D3DPRIMITIVETYPE, _
    MinIndex As Long, _
    NumIndices As Long, _
    StartIndex As Long, _
    PrimitiveCount As Long)

指定項目

object
Direct3DDevice8 オブジェクトを表すオブジェクト式。
PrimitiveType
レンダリングするプリミティブの種類を記述する CONST_D3DPRIMITIVETYPE 列挙のメンバ。「注意」を参照すること。
MinIndex
この呼び出しの間に使用される頂点群に対する最小の頂点インデックス。
NumIndices
この呼び出しで使用されるインデックスの数 (BaseVertexIndex + MinIndex から始まる)。
StartIndex
インデックス配列の中でインデックスの読み取りを開始する位置。
PrimitiveCount
レンダリングするプリミティブの数。使用されるインデックスの数は、プリミティブ カウントの機能とプリミティブの種類である。プリミティブの許容最大数は、D3DCAPS8 構造体の MaxPrimitiveCount メンバをチェックして決定される。

エラー コード

失敗した場合はエラーが発生し、Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

このメソッドは、現在のデータ入力ストリーム セットからインデックス付きプリミティブを描画する。

MinIndex、およびインデックス ストリームのすべてのインデックスは、Direct3DDevice8.SetIndices の呼び出し時に設定される BaseVertexIndex に関連する。

MinIndex パラメータと NumIndices パラメータで、DrawIndexedPrimitive の呼び出しごとに使用する頂点インデックスの範囲を指定する。この 2 つのパラメータを使って、インデックス付けする前の頂点群のシーケンシャルな範囲を処理することで、インデックス付きプリミティブの頂点処理を最適化する。呼び出しの間に使われるインデックスがこの範囲外の頂点を参照することは無効である。

インデックス配列が設定されていない場合、DrawIndexedPrimitive は失敗する。

CONST_D3DPRIMITIVETYPE 列挙の D3DPT_POINTLIST メンバはサポートされていないので、PrimitiveType として指定すべきではない。

参照

Direct3DDevice8.DrawPrimitive、Direct3DDevice8.SetStreamSource、プリミティブのレンダリング


Direct3DDevice8.DrawIndexedPrimitiveUP

ユーザー メモリの配列で指定されているデータで、指定されているジオメトリ プリミティブをレンダリングする。

object.DrawIndexedPrimitiveUP( _
    PrimitiveType As CONST_D3DPRIMITIVETYPE, _
    MinIndex As Long, _
    NumVertices As Long, _
    PrimitiveCount As Long, _
    IndexDataArray As Any, _
    IndexDataFormat As CONST_D3DFORMAT, _
    VertexStreamZeroDataArray As Any, _
    VertexStreamZeroStride As Long)

指定項目

object
Direct3DDevice8 オブジェクトを表すオブジェクト式。
PrimitiveType
レンダリングするプリミティブの種類を記述する CONST_D3DPRIMITIVETYPE 列挙のメンバ。
MinIndex
この呼び出しの間に使用される頂点群に対する、0 (ゼロ) (IndexDataArray の開始位置) を基準とする最小の頂点インデックス。
NumVertices
この呼び出しで使用される頂点の数 (MinIndex. から始まる)。
PrimitiveCount
レンダリングするプリミティブの数。使用されるインデックスの数は、プリミティブ カウントの機能とプリミティブの種類である。プリミティブの許容最大数は、D3DCAPS8 構造体の MaxPrimitiveCount メンバをチェックして決定される。
IndexDataArray
インデックス データが格納されているユーザー メモリの配列の先頭要素。
IndexDataFormat
インデックス データのフォーマットを示す CONST_D3DFORMAT 列挙のメンバ。有効な設定は次のとおりである。
D3DFMT_INDEX16
インデックスはそれぞれ 16 ビットである。
D3DFMT_INDEX32
インデックスはそれぞれ 32 ビットである。
VertexStreamZeroDataArray
頂点ストリームをゼロにするために使用する頂点データを含むユーザー メモリの配列の先頭要素。
VertexStreamZeroStride
Microsoft® Visual Basic® 関数 Len によって返される各頂点のデータ間のストライド (バイト単位)。

エラー コード

失敗した場合はエラーが発生し、Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

このメソッドは、頂点データを頂点バッファに格納できないアプリケーションで使用する。このメソッドは単一の頂点ストリームのみをサポートする。この呼び出しは、頂点ストリームに提供された頂点データのポインタとストライドをゼロにする。ストリーム ゼロ以外の頂点ストリームを参照するカレント頂点シェーダを宣言することはできない (or を宣言するとエラーとなる)。

DrawIndexedPrimitiveUP を呼び出した後、Direct3DDevice8.GetStreamSource で参照されるストリーム ゼロの設定には、ByVal 0 が設定される。また、Direct3DDevice8.SetIndices のインデックス バッファの設定も、ByVal 0 に設定される。

参照

Direct3DDevice8.DrawPrimitiveUP、Direct3DDevice8.SetStreamSource、プリミティブのレンダリング


Direct3DDevice8.DrawPrimitive

現在のデータ入力ストリーム セットからインデックス付きプリミティブをレンダリングする。

object.DrawPrimitive( _
    PrimitiveType As CONST_D3DPRIMITIVETYPE, _
    StartVertex As Long, _
    PrimitiveCount As Long)

指定項目

object
Direct3DDevice8 オブジェクトを表すオブジェクト式。
PrimitiveType
レンダリングするプリミティブの種類を記述する CONST_D3DPRIMITIVETYPE 列挙のメンバ。
StartVertex
ロードする最初の頂点のインデックス。StartVertex を先頭に、正しい頂点数が頂点バッファから読み取られる。
PrimitiveCount
レンダリングするプリミティブの数。プリミティブの許容最大数は、D3DCAPS8 構造体の MaxPrimitiveCount メンバをチェックして決定される。PrimitiveCount は、プリミティブ タイプで指定されたプリミティブの数である。線リストの場合、各プリミティブは 2 つの頂点を持つ。三角形リストの場合、各プリミティブは 3 つの頂点を持つ。

エラー コード

失敗した場合はエラーが発生し、Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

一度に 1 つの三角形を指定して DrawPrimitive を呼び出すべきではない。

参照

Direct3DDevice8.DrawIndexedPrimitive、Direct3DDevice8.SetStreamSource、プリミティブのレンダリング


Direct3DDevice8.DrawPrimitiveUP

ユーザー メモリ ポインタで指定されたデータを、指定されたタイプのジオメトリ プリミティブのシーケンスとしてレンダリングする。

object.DrawPrimitiveUP( _
    PrimitiveType As CONST_D3DPRIMITIVETYPE, _
    PrimitiveCount As Long, _
    VertexStreamZeroDataArray As Any, _
    VertexStreamZeroStride As Long)

指定項目

object
Direct3DDevice8 オブジェクトを表すオブジェクト式。
PrimitiveType
レンダリングするプリミティブの種類を記述する CONST_D3DPRIMITIVETYPE 列挙のメンバ。
PrimitiveCount
レンダリングするプリミティブの数。プリミティブの許容最大数は、D3DCAPS8 構造体の MaxPrimitiveCount メンバをチェックして決定される。
VertexStreamZeroDataArray
頂点ストリームをゼロにするために使用する頂点データを含むユーザー メモリの配列の先頭要素。
VertexStreamZeroStride
各頂点に対するデータの間のストライド (バイト単位)。「注意」を参照すること。

エラー コード

失敗した場合はエラーが発生し、Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

このメソッドは、頂点データを頂点バッファに格納できないアプリケーションで使用する。このメソッドは単一の頂点ストリームのみをサポートする。この呼び出しは、頂点ストリームに提供された頂点データのポインタとストライドをゼロにする。ストリーム ゼロ以外の頂点ストリームを参照するカレント頂点シェーダを宣言することはできない (or を宣言するとエラーとなる)。

次のコードは、Visual Basic の Len 関数を使って VertexStreamZeroStride を決定する方法である。

Dim device As Direct3DDevice8
Dim verts(3) As D3DVERTEX

device.DrawPrimitiveUP D3DPT_TRIANGLELIST, 1, verts(0), Len(vert(0))

頂点データが格納されている配列の先頭要素だけを渡すことに注意する。

DrawPrimitiveUP を呼び出した後、Direct3DDevice8.GetStreamSource で参照されるストリーム ゼロの設定には、ByVal 0 が設定される。

参照

Direct3DDevice8.DrawIndexedPrimitiveUP、Direct3DDevice8.SetStreamSource、プリミティブのレンダリング


Direct3DDevice8.DrawRectPatch

現在設定されているストリームを使って、矩形の高次パッチを描画する。

object.DrawRectPatch( _
    Handle As Long, _
    NumSegments As Single, _
    Surface As Any)

指定項目

object
Direct3DDevice8 オブジェクトを表すオブジェクト式。
Handle
描画する矩形の高次パッチへのハンドル。
NumSegments
テッセレーションするときに高次プリミティブの各エッジを分割するセグメントの数。
Surface
D3DRECTPATCH_INFO 型。描画する矩形の高次パッチを記述する。

エラー コード

失敗した場合はエラーが発生し、Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

参照

Direct3DDevice8.DeletePatch、パッチの描画


Direct3DDevice8.DrawTriPatch

現在設定されているストリームを使って、三角形の高次パッチを描画する。

object.DrawTriPatch( _
    Handle As Long, _
    NumSegments As Single, _
    Surface As Any)

指定項目

object
Direct3DDevice8 オブジェクトを表すオブジェクト式。
Handle
描画する三角形の高次パッチへのハンドル。
NumSegments
テッセレーションするときに高次プリミティブの各エッジを分割するセグメントの数。
Surface
D3DTRIPATCH_INFO 型。描画する三角形の高次パッチを記述する。

エラー コード

失敗した場合はエラーが発生し、Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

参照

Direct3DDevice8.DeletePatch、パッチの描画


Direct3DDevice8.EndScene

Direct3DDevice8.BeginScene メソッドの呼び出しによって開始されたシーンを終了する。

object.EndScene()

指定項目

object
Direct3DDevice8 オブジェクトを表すオブジェクト式。

エラー コード

失敗した場合はエラーが発生し、Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

このメソッドが成功すると、シーンがレンダリングされ、レンダリング後のシーンがデバイス サーフェスに保持される。

シーンのレンダリングが正常に開始された場合は、別のシーンのレンダリングを開始するために Direct3DDevice8.BeginScene メソッドを呼び出す前に、このメソッドを呼び出さなければならない。BeginScene メソッドの呼び出しが失敗している場合は、シーンのレンダリングは開始されていないため、このメソッドを呼び出す必要はない。

参照

Direct3DDevice8.BeginScene


Direct3DDevice8.EndStateBlock

デバイス ステート ブロックの記録を停止してステート ブロックのハンドルを取得するように Microsoft® Direct3D® に指示する。

object.EndStateBlock() As Long

指定項目

object
Direct3DDevice8 オブジェクトを表すオブジェクト式。

戻り値

完了したデバイス ステート ブロックへのハンドルが格納されている変数。この値は、Direct3DDevice8.ApplyStateBlock メソッドおよび Direct3DDevice8.DeleteStateBlock メソッドで使用される。

エラー コード

失敗した場合はエラーが発生し、Err.Number に D3DERR_INVALIDCALL が設定されて、戻り値が無効であるか、または Direct3DDevice8.BeginStateBlock メソッドが呼び出されなかったことが示される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

参照

Direct3DDevice8.ApplyStateBlock、Direct3DDevice8.BeginStateBlock、Direct3DDevice8.CaptureStateBlock、Direct3DDevice8.CreateStateBlock、Direct3DDevice8.DeleteStateBlock


Direct3DDevice8.GetAvailableTextureMem

使用可能なテクスチャ メモリの量の推定値を返す。

object.GetAvailableTextureMem( _
    Pool As CONST_D3DPOOL) As Long

指定項目

object
Direct3DDevice8 オブジェクトを表すオブジェクト式。
Pool
CONST_D3DPOOL 型。チェックするプール タイプを指定する。

戻り値

この関数は、使用可能なテクスチャ メモリの推定値を返す。

エラー コード

失敗した場合はエラーが発生し、Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

返される値は、最も近いメガバイト (MB) に丸められる。このような処理が行われるのは、特定のリソースによるビデオ メモリの消費に影響を与えるアラインメントやほかの問題により、ビデオ メモリの推定値を正確に求めることができないためである。アプリケーションでは、この値を使って、利用できるメモリの大まかな量を推定し、割り当てようとするミップマップのレベル数のようなリソースに関する巨視的な決定を下すことができる。しかし、別のリソースを割り当てるのに十分なメモリが残っているかどうかといった小さなスケールの決定にこの値を使用することはできない。


Direct3DDevice8.GetBackBuffer

デバイスのスワップ チェーンからバック バッファを取得する。

object.GetBackBuffer( _
    BackBuffer As Long, _
    BufferType As CONST_D3DBACKBUFFERTYPE) As Direct3DSurface8

指定項目

object
Direct3DDevice8 オブジェクトを表すオブジェクト式。
BackBuffer
返すバック バッファ オブジェクトのインデックス。バック バッファは 0 からバック バッファの総数 -1 までナンバリングされる。0 の戻り値は最初のバック バッファを示し、フロント バッファではない。このメソッドを使用してフロント バッファにアクセスすることはできない。
BufferType
DirectX 8.0 ではステレオ ビューはサポートされていないので、このパラメータの有効な値は D3DBACKBUFFER_TYPE_MONO だけである。

戻り値

返されたバック バッファのサーフェスを表す Direct3DSurface8 オブジェクト。

エラー コード

BackBuffer がバック バッファの総数以上の場合、エラーが発生し、Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。


Direct3DDevice8.GetClipPlane

デバイスのユーザー定義クリップ面の係数を取得する。

object.GetClipPlane( _
    Index As Long, _
    Plane As D3DPLANE)

指定項目

object
Direct3DDevice8 オブジェクトを表すオブジェクト式。
Index
平面式係数を取得するクリップ面のインデックス。
Plane
設定する一般平面方程式形式のクリップ面係数を含む D3DPLANE 型。「注意」を参照すること。

エラー コード

失敗した場合はエラーが発生し、Err.Number に D3DERR_INVALIDCALL が設定される。このエラーは、Index の値が、そのデバイスでサポートされる最大クリップ面インデックスを超えていることを示す。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

このメソッドで取得する係数は、一般平面方程式の形式になっている。D3DPLANE 型の Plane の値 a、b、c、および d は一般平面方程式が ax + by + cz + d = 0 になるように適用される。ax + by + cz + dw >= 0 である場合、同次座標 (x, y, z, w) のポイントは平面が切り取る半分の空間に表示される。クリップ面上または背後に存在するポイントはシーンからクリッピングされる。

このメソッドで使用される平面式はワールド空間にあり、それ以前に呼び出した Direct3DDevice8.SetClipPlane メソッドによって設定されている。

参照

Direct3DDevice8.SetClipPlane 、 D3DPLANE


Direct3DDevice8.GetClipStatus

クリップ ステータスを取得する。

object.GetClipStatus( _
    ClipStatus As D3DCLIPSTATUS8)

指定項目

object
Direct3DDevice8 オブジェクトを表すオブジェクト式。
ClipStatus
クリップ ステータスを示す D3DCLIPSTATUS8 型。

エラー コード

失敗した場合はエラーが発生し、パラメータが無効の場合は Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

参照

Direct3DDevice8.SetClipStatus


Direct3DDevice8.GetCreationParameters

デバイスの作成パラメータを取得する。

object.GetCreationParameters( _
    CreationParams As D3DDEVICE_CREATION_PARAMETERS)

指定項目

object
Direct3DDevice8 オブジェクトを表すオブジェクト式。
CreationParams
デバイスの作成パラメータを示す D3DDEVICE_CREATION_PARAMETERS 型。

エラー コード

失敗した場合はエラーが発生し、パラメータが無効の場合は Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

このデバイスで表されているアダプタの番号を取得するには、返される D3DDEVICE_CREATION_PARAMETERS 型の AdapterOrdinal メンバを参照する。


Direct3DDevice8.GetCurrentTexturePalette

現在のテクスチャ パレットを取得する。

object.GetCurrentTexturePalette() As Long

指定項目

object
Direct3DDevice8 オブジェクトを表すオブジェクト式。

戻り値

現在のテクスチャ パレットを示す値を返す。

エラー コード

失敗した場合はエラーが発生し、Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

参照

Direct3DDevice8.SetCurrentTexturePalette、テクスチャ パレット


Direct3DDevice8.GetDepthStencilSurface

Direct3DDevice オブジェクトが所有する深度ステンシル サーフェスを取得する。

object.GetDepthStencilSurface() As Direct3DSurface8

指定項目

object
Direct3DDevice8 オブジェクトを表すオブジェクト式。

戻り値

深度ステンシル サーフェスを表す Direct3DSurface8 オブジェクト。

エラー コード

失敗した場合はエラーが発生し、Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

参照

Direct3DDevice8.SetRenderTarget、Direct3DDevice8.CopyRects


Direct3DDevice8.GetDeviceCaps

レンダリング デバイスの能力を取得する。

object.GetDeviceCaps( _
    Caps As D3DCAPS8)

指定項目

object
Direct3DDevice8 オブジェクトを表すオブジェクト式。
Caps
返されるデバイスを記述した D3DCAPS8 型。

エラー コード

失敗した場合はエラーが発生し、Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

GetDeviceCaps は、デバイスがソフトウェア頂点処理モードで使用されているときに、ソフトウェア頂点パイプライン能力を取得する。デバイスが D3DCREATE_SOFTWAREVERTEXPROCESSING を指定して作成されている場合、またはデバイスが D3DCREATE_MIXEDVERTEXPROCESSING を指定して作成され、D3DRS_SOFTWAREVERTEXPROCESSING が TRUE に設定されている場合、ソフトウェア頂点処理モードが選択される。


Direct3DDevice8.GetDirect3D

デバイスを作成した Microsoft® Direct3D® オブジェクトへの参照を返す。

object.GetDirect3D() As Direct3D8

指定項目

object
Direct3DDevice8 オブジェクトを表すオブジェクト式。

戻り値

デバイスを作成した Direct3D オブジェクトを表す Direct3D8 オブジェクト。

エラー コード

失敗した場合はエラーが発生し、Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。


Direct3DDevice8.GetDisplayMode

ディスプレイ モードの空間解像度、色解像度、およびリフレッシュ周波数を取得する。

object.GetDisplayMode( _
    Mode As D3DDISPLAYMODE)

指定項目

object
Direct3DDevice8 オブジェクトを表すオブジェクト式。
Mode
アダプタのディスプレイ モードについてのデータを含む D3DDISPLAYMODE 型。デバイスのディスプレイ モードとは異なり、デバイスがフルスクリーン モードになっていない場合はアクティブでない可能性がある。

エラー コード

失敗した場合はエラーが発生し、Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。


Direct3DDevice8.GetFrontBuffer

デバイスのフロント バッファのコピーを生成し、アプリケーションが提供するシステム メモリ バッファにそのコピーを格納する。

object.GetFrontBuffer( _
    DestSurface As Direct3DSurface8)

指定項目

object
Direct3DDevice8 オブジェクトを表すオブジェクト式。
DestSurface
フロント バッファの内容のコピーを受け取る Direct3DSurface8 オブジェクト。データは、デバイスの出力の一番上の行から始めて一番下の行まで、間にスペースをはさまない連続した行として返される。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DERR_DEVICELOST

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

DirectSurface に返されるバッファには、フロント バッファの表示を標準の 32bpp フォーマットである D3DFMT_A8R8G8B8 に変換したものが格納される。


Direct3DDevice8.GetGammaRamp

スワップ チェーンのガンマ修正ランプを取得する。

object.GetGammaRamp( _
    Ramp As D3DGAMMARAMP)

指定項目

object
Direct3DDevice8 オブジェクトを表すオブジェクト式。
Ramp
アプリケーションが提供する D3DGAMMARAMP 型。ガンマ修正ランプが格納される。

エラー コード

失敗した場合はエラーが発生し、Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

参照

Direct3DDevice8.SetGammaRamp、Direct3D8.CreateDevice


Direct3DDevice8.GetIndices

インデックス データを取得する。

object.GetIndices( _
    RetIndexData As Direct3DIndexBuffer8, _
    RetBaseVertexIndex As Long)

指定項目

object
Direct3DDevice8 オブジェクトを表すオブジェクト式。
RetIndexData
返されたインデックス データを表す Direct3DIndexBuffer8 オブジェクト。
RetBaseVertexIndex
返される頂点インデックスのベース値を保持する変数。この値は、頂点データを参照する前にすべてのインデックスに追加され、頂点ストリームの開始位置を定義する。

エラー コード

失敗した場合はエラーが発生し、Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

インデックス リストの値は、レンダリングするジオメトリを作成するときの頂点リストへのインデックス付けに使われる。

RetBaseVertexIndex パラメータに返される値は、インデックスのベース値を示している。このベース値は、頂点データ ストリームを参照する前にすべてのインデックスに追加される。その結果、頂点データ ストリームの開始位置が設定される。ベースとなる頂点インデックスによって、頂点データ内に配置されている対応するプリミティブの場所に基づいてインデックスを再計算せずに、複数のインデックス付きプリミティブを単一の頂点データのセットにパックすることができる。

参照

Direct3DDevice8.SetIndices


Direct3DDevice8.GetInfo

レンダリング デバイスについての情報を取得する。

object.GetInfo( _
    DevInfoID As Long, _
    Info As Any, _
    Size As Long)

指定項目

object
Direct3DDevice8 オブジェクトを表すオブジェクト式。
DevInfoID
Info に返される情報を識別するために使用される値。
Info
呼び出しが成功した場合に、指定したデバイスの情報を受け取る型。
Size
Microsoft® Visual Basic® の Len 関数によって返されるInfo の型のサイズ (バイト単位)。

エラー コード

失敗した場合はエラーが発生し、Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Visual Basic の「エラー処理」を参照すること。

注意

このメソッドが返す情報は、Microsoft® Direct3D® または基になるデバイス ドライバに関連するものである。このメソッドを使用すると、ドライバで特定の種類の情報およびそれに対応する構造体を宣言できるようになる。これらについては、この SDK では説明されていない。

このメソッドは同期的に実行されるので、低速実行時にはアプリケーションのパフォーマンスが低下する場合がある。シーンのレンダリング時 (Direct3DDevice8.BeginScene を呼び出してから Direct3DDevice8.EndScene を呼び出すまでの間) はこのメソッドを呼び出してはならない。

このメソッドは、製品開発時のパフォーマンス追跡およびデバッグに使用する (Microsoft DirectX® のデバッグ バージョン)。このメソッドは、デバイス データを取得することなく成功する場合がある。ホスト システムに DirectX ランタイムのリテール バージョンがインストールされている場合に、このような状況が発生する。


Direct3DDevice8.GetLight

このデバイスで使用する一連のライト プロパティを取得する。

object.GetLight( _
    Index As Long, _
    Light As D3DLIGHT8)

指定項目

object
Direct3DDevice8 オブジェクトを表すオブジェクト式。
Index
取得するライト プロパティ セットのゼロから始まるインデックス。
Light
取得したライティング パラメータ セットを格納する D3DLIGHT8 型。

エラー コード

失敗した場合はエラーが発生し、パラメータの 1 つが無効な場合は、Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

参照

Direct3DDevice8.SetLight、Direct3DDevice8.GetLightEnable、Direct3DDevice8.LightEnable


Direct3DDevice8.GetLightEnable

デバイス内のライティング パラメータ セットのアクティビティ ステータス (有効/無効) を取得する。

object.GetLightEnable( _
    Index As Long) As Long

指定項目

object
Direct3DDevice8 オブジェクトを表すオブジェクト式。
Index
このメソッドの対象となるライティング パラメータ セットのゼロから始まるインデックス。

戻り値

指定したライティング パラメータのステータスが格納されている変数。呼び出しの後、この変数の値がゼロ以外の場合は、指定されたライティング パラメータが有効であることを示し、0 の場合は無効であることを示す。

エラー コード

失敗した場合はエラーが発生し、Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

参照

Direct3DDevice8.GetLight、Direct3DDevice8.LightEnable、Direct3DDevice8.SetLight


Direct3DDevice8.GetMaterial

デバイスに対する現在のマテリアルのプロパティを取得する。

object.GetMaterial( _
    Material As D3DMATERIAL8)

指定項目

object
Direct3DDevice8 オブジェクトを表すオブジェクト式。
Material
現在のマテリアルのプロパティを格納する D3DMATERIAL8 型。

エラー コード

失敗するエラーが発生し、Err.Number に D3DERR_INVALIDCALL が設定さた場合は、Material パラメータが無効であることを示す。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

参照

Direct3DDevice8.SetMaterial


Direct3DDevice8.GetPaletteEntries

パレット エントリを取得する。

object.GetPaletteEntries( _
    PaletteNumber As Long, _
    ArrayOfEntries As Any)

指定項目

object
Direct3DDevice8 オブジェクトを表すオブジェクト式。
PaletteNumber
取得する特定のパラメータを識別する序数値。
ArrayOfEntries
返されるパレット エントリが格納される PALETTEENTRY 型。「注意」を参照すること。

エラー コード

失敗した場合はエラーが発生し、Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

PALETTEENTRY の詳細については、『Microsoft Platform Software Development Kit (SDK)』を参照すること。Microsoft DirectX® 8.0 では、PALETTEENTRY 構造体の peFlags メンバは、Platform SDK に説明されているようには機能しない。peFlags メンバは、現在、8 ビット パレット化フォーマットのアルファ チャネルである。

参照

Direct3DDevice8.GetCurrentTexturePalette、Direct3DDevice8.SetCurrentTexturePalette、Direct3DDevice8.SetPaletteEntries、テクスチャ パレット


Direct3DDevice8.GetPixelShader

現在設定されているピクセル シェーダを取得する。

object.GetPixelShader() As Long

指定項目

object
Direct3DDevice8 オブジェクトを表すオブジェクト式。

戻り値

返されたピクセル シェーダを表すピクセル シェーダ ハンドル。

エラー コード

失敗した場合はエラーが発生し、Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

参照

Direct3DDevice8.SetPixelShader


Direct3DDevice8.GetPixelShaderConstant

ピクセル シェーダ定数配列中の値を取得する。

object.GetPixelShaderConstant( _
    Register As Long, _
    ConstantData As Any, _
    ConstantCount As Long)

指定項目

object
Direct3DDevice8 オブジェクトを表すオブジェクト式。
Register
ピクセル シェーダ定数配列からのデータの取得を開始する位置のレジスタ アドレス。
ConstantData
ピクセル シェーダ定数配列から取得した値を格納する配列の先頭要素。
ConstantCount
ピクセル シェーダ定数配列から取得する定数の数。各定数は、4 つの Single 値から成る。

エラー コード

失敗した場合はエラーが発生し、Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

このメソッドは、ピクセル シェーダ アセンブラの定数レジスタにある値を取得するために使用する。

参照

Direct3DDevice8.SetPixelShaderConstant


Direct3DDevice8.GetPixelShaderFunction

ピクセル シェーダの機能を取得する。

object.GetPixelShaderFunction( _
    Handle As Long, _
    Data As Any, _
    SizeOfData As Long)

指定項目

object
Direct3DDevice8 オブジェクトを表すオブジェクト式。
Handle
参照するピクセル シェーダへのハンドル。
Data
呼び出しが成功した場合に要求したピクセル シェーダ ハンドルに関連付けられているコードを格納する配列の先頭要素。
SizeOfData
Data の配列のサイズ (バイト単位)。この値が 0 などのように、実際のデータ サイズよりも小さい場合、メソッドはこのパラメータを必要なバッファ サイズに設定し、D3DERR_MOREDATA を返す。Data が ByVal 0 の場合、このパラメータには必要なサイズが設定され、D3D_OK が返される。

エラー コード

失敗した場合はエラーが発生し、Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

ピクセル シェーダの機能は、ブレンディング処理を示している。

参照

Direct3DDevice8.GetPixelShader


Direct3DDevice8.GetRasterStatus

スワップ チェーンが表示されているモニタのラスタを記述する情報を返す。

object.GetRasterStatus() As D3DRASTER_STATUS

指定項目

object
Direct3DDevice8 オブジェクトを表すオブジェクト式。

戻り値

このアダプタによって駆動されるモニタ上のラスタの位置やその他のステータスについての情報が格納されている D3DRASTER_STATUS 型。

エラー コード

失敗した場合はエラーが発生し、pRasterStatus パラメータが無効である場合、またはデバイスが現在の走査線からの読み取りをサポートしていない場合は、Err.Number に D3DERR_INVALIDCALL が設定される。デバイスが走査線からの読み取りをサポートしているかどうかは、D3DCAPS8 の Caps メンバの D3DCAPS_READ_SCANLINE フラグをチェックすることによって調べることができる。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

参照

D3DRASTER_STATUS


Direct3DDevice8.GetRenderState

デバイスに対するレンダリング ステートの値を取得する。

object.GetRenderState( _
    State As CONST_D3DRENDERSTATETYPE) As Long

指定項目

object
Direct3DDevice8 オブジェクトを表すオブジェクト式。
State
調査対象のデバイス ステート変数。このパラメータには、CONST_D3DRENDERSTATETYPE 列挙の任意のメンバを指定できる。

戻り値

照会したレンダリング ステート変数の値が格納された変数。

エラー コード

失敗した場合はエラーが発生し、パラメータの 1 つが無効な場合は、Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

参照

Direct3DDevice8.SetRenderState


Direct3DDevice8.GetRenderTarget

レンダリング ターゲットとして使われる Microsoft® Direct3D® サーフェスへのポインタを取得する。

object.GetRenderTarget() As Direct3DSurface8

指定項目

object
Direct3DDevice8 オブジェクトを表すオブジェクト式。

戻り値

そのデバイスのレンダリング ターゲット サーフェスを表す Direct3DSurface8 オブジェクト。

エラー コード

失敗した場合はエラーが発生し、パラメータの 1 つが無効な場合は、Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

参照

Direct3DDevice8.SetRenderTarget


Direct3DDevice8.GetStreamSource

指定されたデータ ストリームにバインドされている頂点バッファを取得する。

object.GetStreamSource( _
    StreamNumber As Long, _
    RetStreamData As Direct3DVertexBuffer8, _
    RetStride As Long)

指定項目

object
Direct3DDevice8 オブジェクトを表すオブジェクト式。
StreamNumber
0 からストリームの最大数 -1 までの範囲のデータ ストリームを指定する。
RetStreamData
指定したデータ ストリームに対してバインドされた頂点バッファ (返される値) を表す Direct3DVertexBuffer8 オブジェクト。
RetStride
返された成分のストライド (バイト単位)。「注意」を参照すること。

エラー コード

失敗した場合はエラーが発生し、Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

ストリームは成分データの一様な配列として定義されており、各成分は、位置、法線、色などの単一エンティティを表す 1 つ以上の要素で構成されている。

次のコードは、GetStreamSource を呼び出す方法を示している。

Dim device As Direct3DDevice8
Dim retVB As Direct3DVertexBuffer8
Dim retStride As Long

device.GetStreamSource 0, retVB, retStride

GetStreamSource が戻った時点で、retVB と retStride には有効な値が設定されている。

参照

Direct3DDevice8.SetStreamSource


Direct3DDevice8.GetTexture

デバイスのステージに割り当てられているテクスチャを取得する。

object.GetTexture( _
    Stage As Long) As Direct3DBaseTexture8

指定項目

object
Direct3DDevice8 オブジェクトを表すオブジェクト式。
Stage
取得するテクスチャのステージ識別子。ステージ識別子はゼロから始まる。デバイスは最大 8 セットまでテクスチャを持つことができるので、Stage に指定できる最大値は 7 である。

戻り値

取得されたテクスチャを表す Direct3DBaseTexture8 オブジェクト。

エラー コード

失敗した場合はエラーが発生し、Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

参照

Direct3DDevice8.SetTexture、Direct3DDevice8.GetTextureStageState、Direct3DDevice8.SetTextureStageState


Direct3DDevice8.GetTextureStageState

割り当てられているテクスチャのステート値を取得する。

object.GetTextureStageState( _
    Stage As Long, _
    State As CONST_D3DTEXTURESTAGESTATETYPE) As Long

指定項目

object
Direct3DDevice8 オブジェクトを表すオブジェクト式。
Stage
ステートを取得する対象となるテクスチャのステージ識別子。ステージ識別子はゼロから始まる。デバイスは最大 8 セットまでテクスチャを持つことができるので、Stage に指定できる最大値は 7 である。
State
取得するテクスチャのステート。このパラメータには、CONST_D3DTEXTURESTAGESTATETYPE 列挙の任意のメンバを指定できる。

戻り値

ステート値を返す。

エラー コード

失敗した場合はエラーが発生し、Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

参照

Direct3DDevice8.SetTextureStageState、Direct3DDevice8.GetTexture、Direct3DDevice8.SetTexture


Direct3DDevice8.GetTransform

トランスフォーム ステートを示す行列を取得する。

object.GetTransform( _
    TransformType As CONST_D3DTRANSFORMSTATETYPE, _
    Matrix As D3DMATRIX)

指定項目

object
Direct3DDevice8 オブジェクトを表すオブジェクト式。
TransformType
変更対象のデバイス ステート変数。このパラメータには、CONST_D3DTRANSFORMSTATETYPE 列挙の任意のメンバを指定できる。
Matrix
返されたトランスフォーム ステートを示す D3DMATRIX 型。

エラー コード

失敗した場合はエラーが発生し、Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

参照

Direct3DDevice8.SetTransform


Direct3DDevice8.GetVertexShader

現在設定されている頂点シェーダを取得する。

object.GetVertexShader() As Long

指定項目

object
Direct3DDevice8 オブジェクトを表すオブジェクト式。

戻り値

頂点シェーダを表す頂点シェーダ ハンドル。

エラー コード

失敗した場合はエラーが発生し、Direct3DDevice オブジェクトが無効の場合は Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

参照

Direct3DDevice8.SetVertexShader


Direct3DDevice8.GetVertexShaderConstant

頂点シェーダ定数配列中の値を取得する。

object.GetVertexShaderConstant( _
    Register As Long, _
    ConstantData As Any, _
    ConstantCount As Long)

指定項目

object
Direct3DDevice8 オブジェクトを表すオブジェクト式。
Register
頂点シェーダ定数配列からのデータの取得を開始する位置のレジスタ アドレス。
ConstantData
頂点シェーダ定数配列から取得した値を格納する配列の先頭要素。
ConstantCount
頂点シェーダ定数配列から取得する定数の数。各定数は、4 つの Single 値から成る。

エラー コード

失敗した場合はエラーが発生し、Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

このメソッドは、頂点シェーダ アセンブラの定数レジスタにある値を取得するために使用する。

参照

Direct3DDevice8.SetVertexShaderConstant


Direct3DDevice8.GetVertexShaderDeclaration

頂点シェーダの宣言トークン配列を取得する。

object.GetVertexShaderDeclaration( _
    Handle As Long, _
    Data As Any, _
    SizeOfData As Long)

指定項目

object
Direct3DDevice8 オブジェクトを表すオブジェクト式。
Handle
頂点シェーダを参照するハンドル。
Data
呼び出しが成功した場合に要求した頂点シェーダ ハンドルに関連付けられている宣言を格納する配列の先頭要素。
SizeOfData
Data の配列のサイズ (バイト単位)。この値が 0 などのように、実際のデータ サイズよりも小さい場合、メソッドはこのパラメータを必要なバッファ サイズに設定し、D3DERR_MOREDATA を返す。Data が ByVal 0 の場合、このパラメータには必要なサイズが設定され、D3D_OK が返される。

エラー コード

Handle が頂点シェーダへの無効なハンドルの場合は、D3DERR_INVALIDCALL が返される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

頂点シェーダの宣言トークン配列ではシェーダへの入力が定義されており、入力データ ストリーム中の頂点要素をシェーダが使用する方法も含まれる。

参照

Direct3DDevice8.GetVertexShader


Direct3DDevice8.GetVertexShaderFunction

頂点シェーダの機能を取得する。

object.GetVertexShaderFunction( _
    Handle As Long, _
    Data As Any, _
    SizeOfData As Long)

指定項目

object
Direct3DDevice8 オブジェクトを表すオブジェクト式。
Handle
頂点シェーダを参照するハンドル。
Data
呼び出しが成功した場合に要求した頂点シェーダ ハンドルに関連付けられているコードを格納する配列の先頭要素。
SizeOfData
Data の配列のサイズ (バイト単位)。この値が 0 などのように、実際のデータ サイズよりも小さい場合、メソッドはこのパラメータを必要なバッファ サイズに設定し、D3DERR_MOREDATA を返す。Data が ByVal 0 の場合、このパラメータには必要なサイズが設定され、D3D_OK が返される。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DERR_MOREDATA

Handle が頂点シェーダへの無効なハンドルの場合は、D3DERR_INVALIDCALL が返される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

頂点シェーダの機能では、各頂点に適用される処理が定義されている。

参照

Direct3DDevice8.GetVertexShader


Direct3DDevice8.GetViewport

デバイスに現在設定されているビューポート パラメータを取得する。

object.GetViewport( _
    Viewport As D3DVIEWPORT8)

指定項目

object
Direct3DDevice8 オブジェクトを表すオブジェクト式。
Viewport
返されるビューポート パラメータを表す D3DVIEWPORT8 型。

エラー コード

エラーが発生し、Viewport パラメータが無効の場合は Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

参照

Direct3DDevice8.SetViewport


Direct3DDevice8.LightEnable

デバイス内のライティング パラメータ セットを有効または無効にする。

object.LightEnable( _
    Index As Long, _
    Enabled As Long)

指定項目

object
Direct3DDevice8 オブジェクトを表すオブジェクト式。
Index
このメソッドの対象となるライティング パラメータ セットのゼロから始まるインデックス。
Enabled
ライティング パラメータ セットが有効か無効かを示す値。このパラメータに TRUE を設定すると、指定したインデックスのパラメータのライトが有効になり、FALSE を設定すると無効になる。

エラー コード

失敗した場合はエラーが発生し、Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

デバイス内で割り当てられているライト プロパティ セットの範囲外の値を Index に設定すると、LightEnable メソッドは D3DLIGHT8 型で表される光源を以下のプロパティで作成し、有効なステートに Enabled で指定された値を設定する。

メンバ | デフォルト
Type | D3DLIGHT_DIRECTIONAL
Diffuse | (R:1, G:1, B:1, A:0)
Specular | (R:0, G:0, B:0, A:0)
Ambient | (R:0, G:0, B:0, A:0)
Position | (0, 0, 0)
Direction | (0, 0, 1)
Range | 0
Falloff | 0
Attenuation0 | 0
Attenuation1 | 0
Attenuation2 | 0
Theta | 0
Phi | 0

参照

Direct3DDevice8.GetLight、Direct3DDevice8.GetLightEnable、Direct3DDevice8.SetLight


Direct3DDevice8.MultiplyTransform

デバイスのワールド行列、ビュー行列、または射影行列に、指定された行列を乗算する。

object.MultiplyTransform( _
    TransformType As CONST_D3DTRANSFORMSTATETYPE, _
    Matrix As D3DMATRIX)

指定項目

object
Direct3DDevice8 オブジェクトを表すオブジェクト式。
TransformType
変更するデバイス行列を示す CONST_D3DTRANSFORMSTATETYPE 列挙のメンバ。最も一般的な設定は D3DTS_WORLD で、ワールド行列を変更するが、必要であれば、ビュー行列や射影行列を変更するように指定することもできる。
Matrix
現在のトランスフォームを変更する D3DMATRIX 型。

エラー コード

失敗した場合はエラーが発生し、Err.Number が設定される。パラメータのいずれかが無効な場合は D3DERR_INVALIDCALL を返す。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

アプリケーションが、トランスフォームの階層構造を使って動作するために、MultiplyTransform メソッドを使用することも考えられる。たとえば、腕を表すジオメトリとトランスフォームは、以下の階層で構成することができる。

shoulder_transformation
    upper_arm geometry
    elbow transformation
        lower_arm geometry
        wrist transformation
            hand geometry

アプリケーションは、この階層をレンダリングするのに、以下の一連の呼び出しを使用してもよい (この擬似コードでは、すべてのパラメータは示されていない)。

Direct3DDevice8.SetTransform(D3DTS_WORLD,
    shoulder_transform)
Direct3DDevice8.DrawPrimitive(upper_arm)
Direct3DDevice8.MultiplyTransform(D3DTS_WORLD,
    elbow_transform)
Direct3DDevice8.DrawPrimitive(lower_arm)
Direct3DDevice8.MultiplyTransform(D3DTS_WORLD,
    wrist_transform)
Direct3DDevice8.DrawPrimitive(hand)

参照

Direct3DDevice8.DrawPrimitive、Direct3DDevice8.SetTransform


Direct3DDevice8.Present

デバイスが所有するバック バッファのシーケンスの中で次のコンテンツを提示する。

object.Present( _
    SourceRect As Any, _
    DestRect As Any, _
    DestWindowOverride As Long, _
    DirtyRegion As Any)

指定項目

object
Direct3DDevice8 オブジェクトを表すオブジェクト式。
SourceRect
スワップ チェーンが D3DSWAPEFFECT_COPY または D3DSWAPEFFECT_COPY_VSYNC で作成されていない限り、値は ByVal 0 である必要がある。SourceRect は転送元矩形を含む型である。ByVal が 0 の場合、転送元サーフェス全体が表示される。矩形が転送元サーフェスを超えた場合、矩形は転送元サーフェスにクリッピングされる。
DestRect
スワップ チェーンが D3DSWAPEFFECT_COPY または D3DSWAPEFFECT_COPY_VSYNC で作成されていない限り、値は ByVal 0 である必要がある。DestRect は、ウィンドウのクライアント座標に転送先矩形を含む型である。ByVal が 0 の場合は、クライアント領域全体が格納される。矩形が転送先のクライアント領域を越えた場合、矩形は転送先のクライアント領域にクリッピングされる。
DestWindowOverride
クライアント領域がこのプレゼンテーションの対象として扱われる転送先ウィンドウ。この値が 0 (ゼロ) の場合は、D3DPRESENT_PARAMETERS の hWndDeviceWindow メンバが使用される。
DirtyRegion
このパラメータは使用されず、ByVal 0 に設定する必要がある。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DERR_DEVICELOST

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

必要に応じて、転送元矩形内のピクセルをターゲット ウィンドウのクライアント領域の転送先矩形に転送するために拡大処理が適用される。

次のコードは、デフォルトの場合に Present を呼び出す方法を示している。

Dim device As Direct3DDevice8
device.Present ByVal 0, ByVal 0, 0, ByVal 0

デフォルトの場合、Any 型をとるパラメータには ByVal 0 を指定する必要があることに注意すること。Any 型のパラメータに 0 (ゼロ) を指定した場合は、エラーが発生し、メソッドは失敗する。

参照

Direct3DDevice8.Reset


Direct3DDevice8.ProcessVertices

頂点シェーダで定義されている頂点処理を一連の入力データ ストリームに適用し、インターリーブされた頂点データの単一ストリームを生成して転送先頂点バッファに格納する。

object.ProcessVertices( _
    SrcStartIndex As Long, _
    DestIndex As Long, _
    VertexCount As Long, _
    DestBuffer As Direct3DVertexBuffer8, _
    Flags As Long)

指定項目

object
Direct3DDevice8 オブジェクトを表すオブジェクト式。
SrcStartIndex
ロードする最初の頂点のインデックス。
DestIndex
結果を格納する転送先頂点バッファ内の最初の頂点のインデックス。
VertexCount
処理する頂点の数。
DestBuffer
Direct3DVertexBuffer8 オブジェクト。インターリーブされた頂点データのストリームを表す格納先頂点バッファ。
Flags
処理オプション。デフォルト処理に対してはこのパラメータを 0 に設定する。D3DPV_DONOTCOPYDATA に設定すると、頂点の処理に無関係な頂点データをコピー先バッファにコピーするのを防ぐことができる。

エラー コード

失敗した場合はエラーが発生し、Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

転送先頂点バッファ DestBuffer は、ゼロ以外の FVF パラメータを指定して作成しなければならない。Direct3DDevice8.CreateVertexBuffer メソッドの呼び出しにおいて指定する FVF コードは、転送先頂点バッファに格納される頂点要素を指定している。

参照

デバイスの種類と頂点処理の要件


Direct3DDevice8.Reset

スワップ チェーンのタイプ、サイズ、およびフォーマットを変更する。

object.Reset( _
    PresentationParameters As D3DPRESENT_PARAMETERS)

指定項目

object
Direct3DDevice8 オブジェクトを表すオブジェクト式。
PresentationParameters
新しいプレゼンテーション パラメータを示す D3DPRESENT_PARAMETERS 型。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DERR_OUTOFVIDEOMEMORY
E_OUTOFMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

Reset の呼び出しが失敗すると、デバイスは "消失" 状態 (TestCooperativeLevel の呼び出しからの戻り値 D3DERR_DEVICELOST が示す) になる。ただし、デバイスが既に "非リセット" 状態 (TestCooperativeLevel の呼び出しからの戻り値 D3DERR_DEVICENOTRESET が示す) の場合は除く。消失したデバイスのコンテキストにおける Reset の使用の詳細については、「Direct3DDevice8.TestCooperativeLevel」および「消失したデバイス」を参照すること。

Reset を呼び出すと、すべてのテクスチャ メモリ サーフェスが失われて、管理下のテクスチャがビデオ メモリからフラッシュされて、すべてのステート情報がクリアされる。デバイスに対して Reset メソッドを呼び出す前に、アプリケーションでは明示的なレンダリング ターゲット、深度ステンシル サーフェス、追加スワップ チェーン、およびデバイスに関連付けられている D3DPOOL_DEFAULT リソースを解放する必要がある。

スワップ チェーンのタイプには、フルスクリーンとウィンドウがある。新しいスワップ チェーンがフルスクリーンの場合、アダプタは新しいサイズに合ったディスプレイ モードに設定される。

Reset が失敗した場合、呼び出すことができる有効なメソッドは Reset および Direct3DDevice8.TestCooperativeLevel だけである。その他のメソッドを呼び出すと、例外になる場合がある。

参照

CONST_D3DSWAPEFFECT、D3DPRESENT_PARAMETERS、Direct3DDevice8.Present


Direct3DDevice8.ResourceManagerDiscardBytes

リソース マネージャを呼びだして、メモリを解放する。

object.ResourceManagerDiscardBytes( _
    NumberOfBytes As Long)

指定項目

object
Direct3DDevice8 オブジェクトを表すオブジェクト式。
NumberOfBytes
破棄の対象となるバイトの数。0 (ゼロ) を指定すると、リソース マネージャは全バイトを破棄する。

エラー コード

失敗した場合はエラーが発生し、Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

リソース マネージャは、目標のバイト数に達するまで、メモリ割り当ての解放を行う。リソース マネージャは、最低使用頻度方式 (LRU) の優先順位決定技法に従う。

解放されるバイト数が連続していることは保証されないので、このメソッドを呼び出した後、Bytes で指定したバイト数を使用するリソースを作成できない場合がある。


Direct3DDevice8.SetClipPlane

デバイスのユーザー定義クリップ面の係数を設定する。

object.SetClipPlane( _
    Index As Long, _
    Plane As D3DPLANE)

指定項目

object
Direct3DDevice8 オブジェクトを表すオブジェクト式。
Index
平面方程式の係数を設定するクリップ面のインデックス。
Plane
設定する一般平面方程式形式のクリップ面係数を含む D3DPLANE 型。「注意」を参照すること。

エラー コード

失敗した場合はエラーが発生し、Err.Number に D3DERR_INVALIDCALL が設定される。このエラーは、Index の値が、そのデバイスでサポートされる最大クリップ面インデックスを超えていることを示す。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

このメソッドで設定する係数は、一般平面方程式の形式になっている。D3DPLANE 型の Plane の値 a、b、c、および d は一般平面方程式が ax + by + cz + d = 0 になるように適用される。ax + by + cz + dw >= 0 である場合、同次座標 (x, y, z, w) のポイントは平面が切り取る半分の空間に表示される。クリップ面上または背後に存在するポイントはシーンからクリッピングされる。

固定機能パイプラインが使用される場合、平面方程式はワールド空間にあると仮定される。プログラム可能なパイプラインが使用される場合、平面方程式はクリップ空間 (出力頂点と同じ空間) にあると仮定される。

このメソッドは、設定されているクリップ面の式を有効にするものではない。クリップ面を有効にするには、CONST_D3DRENDERSTATETYPE 列挙の D3DRS_CLIPPLANEENABLE レンダリング ステート定数を使用する。

参照

Direct3DDevice8.GetClipPlane


Direct3DDevice8.SetClipStatus

クリップ ステータスを設定する。

object.SetClipStatus( _
    ClipStatus As D3DCLIPSTATUS8)

指定項目

object
Direct3DDevice8 オブジェクトを表すオブジェクト式。
ClipStatus
設定するクリップ ステータスを示す D3DCLIPSTATUS8 型。

エラー コード

失敗した場合はエラーが発生し、ClipStatus パラメータが無効の場合は Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

参照

Direct3DDevice8.GetClipStatus


Direct3DDevice8.SetCurrentTexturePalette

現在のテクスチャ パレットを設定する。

object.SetCurrentTexturePalette( _
    PaletteNumber As Long)

指定項目

object
Direct3DDevice8 オブジェクトを表すオブジェクト式。
PaletteNumber
現在のテクスチャ パレットとして設定するテクスチャ パレットを指定する値。

エラー コード

失敗した場合はエラーが発生し、Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

単一の論理パレットがデバイスに関連付けられ、すべてのテクスチャ ステージで共有される。

参照

Direct3DDevice8.GetCurrentTexturePalette、テクスチャ パレット


Direct3DDevice8.SetCursorPosition

カーソルの位置を設定し、オプションを更新する。

object.SetCursorPosition( _
    XScreenSpace As Long, _
    YScreenSpace As Long
    Flags As CONST_D3DSCPFLAGS)

指定項目

object
Direct3DDevice8 オブジェクトを表すオブジェクト式。
XScreenSpace
スクリーン空間座標で表したカーソルの新しい X 位置。「注意」を参照すること。
YScreenSpace
スクリーン空間座標で表したカーソルの新しい Y 位置。「注意」を参照すること。
Flags
カーソルの更新オプションを指定する。現在、定義されているフラグは 1 つだけである。

D3DCURSOR_IMMEDIATE_UPDATE

リフレッシュ レートでカーソルを更新する。

このフラグを指定した場合、システムは最低ディスプレイのリフレッシュ レートの半分の速度でカーソルを更新することを保証するが、ディスプレイのリフレッシュ レートより頻繁に更新することはない。このフラグを指定しない場合、このメソッドはカーソルの更新を次の Direct3DDevice8.Present の呼び出しまで遅延させる。このデフォルトの動作は、通常、フラグを設定した場合よりもパフォーマンスが向上する。ただし、Present の呼び出しの頻度が高く、ユーザーがカーソルの動きに重大な遅延を感じるようであれば、アプリケーションでこのフラグを設定すべきである。

エラー コード

失敗した場合はエラーが発生し、Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

フルスクリーン モードで実行している場合、スクリーン空間座標はバック バッファ座標に変換されて、現在のディスプレイ モードに合わせて適切にスケーリングされる。ウィンドウ モードで実行している場合は、スクリーン空間座標はデスクトップ座標に変換される。カーソル イメージは、指定された位置から Direct3DDevice8.SetCursorProperties メソッドで指定されているホットスポット オフセットの値を引いた位置に描画される。

カーソルが Direct3DDevice8.ShowCursor によって隠されている場合、カーソルは描画されない。

参照

Direct3DDevice8.SetCursorProperties、Direct3DDevice8.ShowCursor


Direct3DDevice8.SetCursorProperties

カーソルのプロパティを設定する。

object.SetCursorProperties( _
    XHotSpot As Long, _
    YHotSpot As Long, _
    CursorSurface As Direct3DSurface8)

指定項目

object
Direct3DDevice8 オブジェクトを表すオブジェクト式。
XHotSpot
カーソルの左上隅を基準としてカーソルの内部に向かう X 座標オフセット (ピクセル単位)。カーソルの中心と見なされる。カーソルが新しい位置に指定された場合、イメージは、この新しい位置からのオフセットに描かれる。この新しい位置は、その位置からホット スポットの座標を引くことによって決定された位置である。
YHotSpot
カーソルの左上隅を基準としてカーソルの内部に向かう Y 座標オフセット (ピクセル単位)。カーソルの中心と見なされる。カーソルが新しい位置に指定された場合、イメージは、この新しい位置からのオフセットに描かれる。この新しい位置は、その位置からホット スポットの座標を引くことによって決定された位置である。
CursorSurface
Direct3DSurface8 オブジェクト。このパラメータは、8888 ARGB サーフェス (フォーマットは D3DFORMAT_A8R8G8B8) をポイントしていなければならない。このサーフェスのコンテンツは、カーソルの表示に使われる内部バッファにコピーされて、同時にフォーマット変換が行われる場合がある。このサーフェスのディメンジョンはディスプレイ モードのディメンジョンより小さくなければならず、各方向とも 2 の累乗でなければならない。ただし、両方向が同じ大きさでなくてもかまわない。アルファ チャネルは、0.0 または 1.0 でなければならない。

エラー コード

失敗した場合はエラーが発生し、Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

このメソッドは、Microsoft® Win32® API の ShowCursor および SetCursor 関数とは独立している。アプリケーションでは、Win32 カーソルまたは Microsoft Direct3D® カーソルのいずれかを使用し、両方を使用してはならない。

アプリケーションでは、D3DCAPS8 型の適切なメンバを調べることで、カーソルで利用可能なハードウェア サポートを確認できる。一般に、ハードウェアがサポートするのは 32 × 32 のカーソルだけである。さらに、ウィンドウ モードでは、システムがサポートできるのも 32 × 32 のカーソルだけである。その場合でも SetCursorProperties は成功するが、カーソルはこのサイズに縮小されて、ホットスポットは適切にスケーリングされる可能性がある。

参照

Direct3DDevice8.SetCursorPosition、Direct3DDevice8.ShowCursor、D3DCAPS8


Direct3DDevice8.SetGammaRamp

非明示的なスワップ チェーンのガンマ修正ランプを設定する。

object.SetGammaRamp( _
    Flags As Long, _
    Ramp As D3DGAMMARAMP)

指定項目

object
Direct3DDevice8 オブジェクトを表すオブジェクト式。
Flags
修正を適用するかどうかを指定する。ガンマ修正を行うといっそう一貫性のある表示が得られるが、処理オーバーヘッドが発生する可能性があるので、頻繁に使用すべきではない。全画面を赤くフラッシュさせるような短時間のエフェクトに対してキャリブレーションを行う必要はないが、長時間のガンマ変化に対してはキャリブレーションを行う必要がある。CONST_D3DSGRFLAGS 列挙で定義されている値のいずれかを設定できる。
Ramp
非明示的なスワップ チェーンに設定するガンマ修正ランプを表す D3DGAMMARAMP 型。

エラー コード

失敗した場合はエラーが発生し、Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

Microsoft® Direct3D® for Microsoft DirectX® 8.0 はデバイスのプロパティとして 1 つのスワップ チェーンを持っているため、各デバイスに対して、常に少なくても 1 つのスワップ チェーン (非明示的なスワップ チェーン) が存在する。

ガンマ ランプはスワップ チェーンのプロパティなので、スワップ チェーンをウィンドウ化するときは、ガンマ ランプを適用できる。

ガンマ ランプは直ちに有効になる。VSYNC の待機は発生しない。

デバイスがスワップ チェーンの現在のプレゼンテーション モード (フルスクリーンまたはウィンドウ) においてガンマ ランプをサポートしていない場合でも、エラーが返ることはない。アプリケーションでは、D3DCAPS8 型の Caps2 メンバの D3DCAPS2_FULLSCREENGAMMA 能力ビットおよび D3DCAPS2_CANCALIBRATEGAMMA 能力ビットを調べて、デバイスの能力および口径測定器がインストールされているかどうかを判断できる。

参照

Direct3D8.CreateDevice、Direct3DDevice8.GetGammaRamp


Direct3DDevice8.SetIndices

インデックス データを設定する。

object.SetIndices( _
    IndexData As Direct3DIndexBuffer8, _
    BaseVertexIndex As Long)

指定項目

object
Direct3DDevice8 オブジェクトを表すオブジェクト式。
IndexData
設定するインデックス データを表す Direct3DIndexBuffer8 オブジェクト。
BaseVertexIndex
頂点インデックスのベース値。この値は、頂点データを参照する前にすべてのインデックスに追加され、頂点ストリームの開始位置を定義する。

エラー コード

失敗した場合はエラーが発生し、Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

SetIndices メソッドは、インデックス バッファに現在のインデックス配列を設定する。単一のインデックス セットを使って、すべてのストリームにインデックスが付けられる。

BaseVertexIndex パラメータでは、インデックスに対するベース値を指定する。このベース値は、頂点データ ストリームを参照する前にすべてのインデックスに追加される。その結果、頂点データ ストリームの開始位置が設定される。ベースとなる頂点インデックスによって、頂点データ内に配置されている対応するプリミティブの場所に基づいてインデックスを再計算せずに、複数のインデックス付きプリミティブを単一の頂点データのセットにパックすることができる。

参照

Direct3DDevice8.GetIndices


Direct3DDevice8.SetLight

このデバイスに一連のライト プロパティを割り当てる。

object.SetLight( _
    Index As Long, _
    Light As D3DLIGHT8)

指定項目

object
Direct3DDevice8 オブジェクトを表すオブジェクト式。
Index
設定するライト プロパティ セットのゼロから始まるインデックス。このインデックスにライト プロパティ セットが存在する場合は、Light で指定した新しいプロパティで上書きされる。
Light
設定するライティング パラメータが格納されている D3DLIGHT8 型。

エラー コード

失敗した場合はエラーが発生し、Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

参照

Direct3DDevice8.GetLight、Direct3DDevice8.GetLightEnable、Direct3DDevice8.LightEnable


Direct3DDevice8.SetMaterial

デバイスにマテリアル プロパティを設定する。

object.SetMaterial( _
    Material As D3DMATERIAL8)

指定項目

object
Direct3DDevice8 オブジェクトを表すオブジェクト式。
Material
設定するマテリアル プロパティが記述されている D3DMATERIAL8 型。

エラー コード

メソッドが失敗すると、エラーが発生し、Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

参照

Direct3DDevice8.GetMaterial


Direct3DDevice8.SetPaletteEntries

パレット エントリを設定する。

object.SetPaletteEntries( _
    PaletteNumber As Long, _
    ArrayOfEntries As Any)

指定項目

object
Direct3DDevice8 オブジェクトを表すオブジェクト式。
PaletteNumber
実行する処理の対象となる特定のパラメータを識別する序数値。
ArrayOfEntries
設定するパレット エントリを含む配列の先頭の要素。この配列の PALETTEENTRY 型の数は 256 であると仮定されている。「注意」を参照すること。

エラー コード

失敗した場合はエラーが発生し、Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

PALETTEENTRY の詳細については、『Microsoft Platform Software Development Kit (SDK)』を参照すること。Microsoft DirectX® 8.0 では、PALETTEENTRY 構造体の peFlags メンバは、Platform SDK に説明されているようには機能しない。peFlags メンバは、現在、8 ビット パレット化フォーマットのアルファ チャネルである。

単一の論理パレットがデバイスに関連付けられ、すべてのテクスチャ ステージで共有される。

次のコードは、SetPaletteEntries を呼び出す方法を示している。

Dim device As Direct3DDevice8
Dim pal(255) As PALETTEENTRY

'パレット エントリ配列の最初の要素を渡す。
device.SetPaletteEntries 255, pal(0)

PaletteNumber が渡されるパレット エントリの配列のサイズと一致しているようにする。

参照

Direct3DDevice8.GetCurrentTexturePalette、Direct3DDevice8.GetPaletteEntries、Direct3DDevice8.SetCurrentTexturePalette、テクスチャ パレット


Direct3DDevice8.SetPixelShader

以前作成したピクセル シェーダを現在のピクセル シェーダに設定する。

object.SetPixelShader( _
    PixelShaderHandle As Long)

指定項目

object
Direct3DDevice8 オブジェクトを表すオブジェクト式。
PixelShaderHandle
設定するピクセル シェーダを指定するピクセル シェーダへのハンドル。このパラメータでは、Direct3DDevice8.CreatePixelShader から返るハンドルを使用できる。

エラー コード

失敗した場合はエラーが発生し、Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

参照

Direct3DDevice8.GetPixelShader


Direct3DDevice8.SetPixelShaderConstant

ピクセル定数配列に値を設定する。

object.SetPixelShaderConstant( _
    Register As Long, _
    ConstantData As Any, _
    ConstantCount As Long)

指定項目

object
Direct3DDevice8 オブジェクトを表すオブジェクト式。
Register
ピクセル定数配列へのデータのロードを開始するレジスタ アドレス。
ConstantData
ピクセル定数配列にロードする値を保持している配列の先頭要素。
ConstantCount
ピクセル定数配列にロードする定数の数。各定数は、4 つの Single 値から成る。

エラー コード

失敗した場合はエラーが発生し、Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

このメソッドは、ピクセル シェーダ アセンブラの定数レジスタに値をロードするために使用する。

参照

Direct3DDevice8.GetPixelShaderConstant


Direct3DDevice8.SetRenderState

単一デバイスのレンダリング ステート パラメータを設定する。

object.SetRenderState( _
    State As CONST_D3DRENDERSTATETYPE, _
    Value As Long)

指定項目

object
Direct3DDevice8 オブジェクトを表すオブジェクト式。
State
変更対象のデバイス ステート変数。このパラメータには、CONST_D3DRENDERSTATETYPE 列挙の任意のメンバを指定できる。
Value
デバイスのレンダリング ステートに設定する新しい値。このパラメータの意味は State で指定した値によって決まる。たとえば、State が D3DRS_SHADEMODE の場合、第 2 パラメータは CONST_D3DSHADEMODE 列挙のメンバのいずれかである。

エラー コード

失敗した場合はエラーが発生し、Err.Number にエラー コードが設定される。パラメータのいずれかが無効な場合のエラー コードは D3DERR_INVALIDCALL である。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

参照

Direct3DDevice8.GetRenderState、Direct3DDevice8.SetTransform


Direct3DDevice8.SetRenderTarget

デバイスに新しいカラー バッファと深度バッファの一方または両方を設定する。

object.SetRenderTarget( _
    NewRenderTarget As Direct3DSurface8, _
    NewDepthStencil As Direct3DSurface8)

指定項目

object
Direct3DDevice8 オブジェクトを表すオブジェクト式。
NewRenderTarget
新しいカラー バッファ。Nothing の場合は、既存のカラー バッファがそのまま使われる。このパラメータが Nothing でない場合は、新しいレンダリング ターゲットの参照カウントがインクリメントされる。デバイスには、常に、カラー バッファが関連付けられていなければならない。

新しいレンダリング ターゲットのサーフェスには、少なくとも D3DUSAGE_RENDERTARGET が指定されていなければならない。

NewDepthStencil
新しい深度ステンシル バッファ。深度ステンシル バッファが存在する場合は解放される。このパラメータが Nothing でない場合は、新しい深度ステンシル バッファ サーフェスの参照カウントがインクリメントされる。Direct3DDevice8.GetDepthStencilSurface から返る Direct3DSurface8 オブジェクトを渡すことで、深度バッファを変更しないでレンダリング ターゲットを変更できる。

新しい深度ステンシル サーフェスには、少なくとも D3DUSAGE_DEPTHSTENCIL と D3DPOOL_DEFAULT が指定されていなければならない。

エラー コード

失敗した場合はエラーが発生し、NewRenderTarget または NewDepthStencil が Nothing ではない無効な値の場合、あるいは新しい深度バッファが新しいカラー バッファまたは引き続き使われるカラー バッファより小さい場合は、Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

このメソッドを使ってカラー バッファと深度ステンシル サーフェスを同じデバイスに関連付けると、両者はペアになる。

SetRenderTarget を呼び出して以前の深度ステンシル サーフェスとデバイスの関連を切断した後でも、前の深度ステンシル サーフェスのコンテンツは保持される。そのサーフェスをデバイスと再び関連付けると、新しい深度ステンシル サーフェスとペアにされているカラー バッファのサイズとフォーマットが、深度ステンシル サーフェスと最後にペアになっていたカラー バッファと同じならば、サーフェスのコンテンツは変更されない。

参照

Direct3DDevice8.CreateDepthStencilSurface、Direct3DDevice8.GetDepthStencilSurface


Direct3DDevice8.SetStreamSource

頂点バッファをデバイスのデータ ストリームにバインドする。

object.SetStreamSource( _
    StreamNumber As Long, _
    StreamData As Direct3DVertexBuffer8, _
    Stride As Long)

指定項目

object
Direct3DDevice8 オブジェクトを表すオブジェクト式。
StreamNumber
0 からストリームの最大数 -1 までの範囲のデータ ストリームを指定する。
StreamData
指定したデータ ストリームに対してバインドする頂点バッファを表す Direct3DVertexBuffer8 オブジェクト。
Stride
成分のストライド (バイト単位)。「注意」を参照すること。

エラー コード

失敗した場合はエラーが発生し、Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

柔軟な頂点フォーマット (FVF) 頂点シェーダを使用する場合、SetStreamSource のストリーム頂点ストライドは、FVF から計算された頂点サイズと一致していなければならない。この宣言を使用する場合、SetStreamSource のストリーム頂点ストライドは、宣言から計算されたストリーム サイズ以上でなければならない。

SetStreamSource メソッドは、頂点バッファをデバイスのデータ ストリームにバインドする。詳細については、「ストリーム ソースの設定」を参照すること。

参照

Direct3DDevice8.DrawIndexedPrimitive、Direct3DDevice8.DrawIndexedPrimitiveUP、Direct3DDevice8.DrawPrimitive、Direct3DDevice8.DrawPrimitiveUP、Direct3DDevice8.GetStreamSource


Direct3DDevice8.SetTexture

テクスチャをデバイスのステージに割り当てる。

object.SetTexture( _
    Stage As Long, _
    Texture As Direct3DBaseTexture8)

指定項目

object
Direct3DDevice8 オブジェクトを表すオブジェクト式。
Stage
テクスチャを設定するステージ識別子。ステージ識別子はゼロから始まる。デバイスは最大 8 セットまでテクスチャを持つことができるので、Stage に指定できる最大値は 7 である。
Texture
設定するテクスチャを表す Direct3DBaseTexture8 オブジェクト。ミップマップ テクスチャやキューブ テクスチャなどのように複雑なテクスチャの場合、このパラメータはトップレベルのサーフェスでなければならない。

エラー コード

失敗した場合はエラーが発生し、Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

このメソッドは、割り当てられているテクスチャ サーフェスの参照カウントをインクリメントし、以前に選択されたテクスチャがある場合にはその参照カウントをデクリメントする。テクスチャが不要になった場合、該当するステージのテクスチャを Nothing に設定する。この処理を行わないと、メモリ リークが発生する。

参照

Direct3DDevice8.GetTexture、Direct3DDevice8.GetTextureStageState、Direct3DDevice8.SetTextureStageState


Direct3DDevice8.SetTextureStageState

現在割り当てられているテクスチャにステート値を設定する。

object.SetTextureStageState( _
    Stage As Long, _
    Type As CONST_D3DTEXTURESTAGESTATETYPE, _
    Value As Long)

指定項目

object
Direct3DDevice8 オブジェクトを表すオブジェクト式。
Stage
ステート値を設定するテクスチャのステージ識別子。ステージ識別子はゼロから始まる。デバイスは最大 8 セットまでテクスチャを持つことができるので、Stage に指定できる最大値は 7 である。
Type
設定するテクスチャ ステート。このパラメータには、CONST_D3DTEXTURESTAGESTATETYPE 列挙の任意のメンバを指定できる。
Value
設定するステート値。この値の意味は、Type パラメータによって決まる。

エラー コード

失敗した場合はエラーが発生し、Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

参照

Direct3DDevice8.GetTextureStageState、Direct3DDevice8.GetTexture、Direct3DDevice8.SetTexture


Direct3DDevice8.SetTransform

単一デバイスのトランスフォーム関連ステートを設定する。

object.SetTransform( _
    TransformType As CONST_D3DTRANSFORMSTATETYPE, _
    Matrix As D3DMATRIX)

指定項目

object
Direct3DDevice8 オブジェクトを表すオブジェクト式。
TransformType
変更対象のデバイス ステート変数。このパラメータには、CONST_D3DTRANSFORMSTATETYPE 列挙の任意のメンバを指定できる。
Matrix
現在のトランスフォームを変更する D3DMATRIX 型。

エラー コード

失敗した場合はエラーが発生し、パラメータの 1 つが無効な場合は、Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

参照

Direct3DDevice8.GetTransform、Direct3DDevice8.SetRenderState


Direct3DDevice8.SetVertexShader

以前に作成した頂点シェーダ、または柔軟な頂点フォーマット (FVF) の固定機能シェーダに、現在の頂点シェーダを設定する。

object.SetVertexShader( _
    VertexShaderHandle As Long)

指定項目

object
Direct3DDevice8 オブジェクトを表すオブジェクト式。
VertexShaderHandle
設定する頂点シェーダを指定する頂点シェーダへのハンドル。このパラメータの値として、Direct3DDevice8.CreateVertexShader から返るハンドルまたは FVF コードを使用できる。FVF コードは柔軟な頂点フォーマット フラグの組み合わせである。

エラー コード

失敗した場合はエラーが発生し、Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

ハンドルとして FVF コードを使用すると、固定機能の頂点シェーダが有効になり、ストリーム ゼロから読み込まれる FVF コードのコンテンツと一致する非明示的な宣言が使われる。FVF 指定のシェーダをデバイスにバインドすると、ストリーム ゼロだけが参照される。

参照

Direct3DDevice8.GetVertexShader


Direct3DDevice8.SetVertexShaderConstant

頂点定数配列に値を設定する。

object.SetVertexShaderConstant( _
    Register As Long, _
    ConstantData As Any, _
    ConstantCount As Long)

指定項目

object
Direct3DDevice8 オブジェクトを表すオブジェクト式。
Register
頂点定数配列へのデータのロードを開始するレジスタ アドレス。
ConstantData
頂点定数配列にロードする値を保持している配列の先頭要素。
ConstantCount
頂点定数配列にロードする定数の数。各定数は、4 つの Single 値から成る。

エラー コード

失敗した場合はエラーが発生し、Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

このメソッドは、頂点シェーダ アセンブラの定数レジスタに値をロードするために使用する。トランスフォーム行列をロードするときは、アプリケーションはその行と列を転置してから、連続した定数レジスタにロードする必要がある。

参照

Direct3DDevice8.GetVertexShaderConstant


Direct3DDevice8.SetViewport

デバイスにビューポート パラメータを設定する。

object.SetViewport( _
    Viewport As D3DVIEWPORT8)

指定項目

object
Direct3DDevice8 オブジェクトを表すオブジェクト式。
Viewport
設定するビューポート パラメータを指定する D3DVIEWPORT8 型。

エラー コード

失敗した場合はエラーが発生し、Err.Number に D3DERR_INVALIDPARAMS が設定され、Viewport パラメータが無効であることが示される。

D3DVIEWPORT8 型で記述するビューポート パラメータが、レンダリング ターゲット サーフェス内に存在できない領域を記述している場合、メソッドは失敗し、D3DERR_INVALIDCALL を返す。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

Direct3DDevice8.BeginScene と Direct3DDevice8.EndScene の間での SetViewPort の呼び出しは、ジオメトリを描画する前に行わなければならない。

参照

Direct3DDevice8.GetViewport


Direct3DDevice8.ShowCursor

カーソルを表示または隠蔽する。

object.ShowCursor( _
    bShow As Long) As Long

指定項目

object
Direct3DDevice8 オブジェクトを表すオブジェクト式。
bShow
bShow に 0 でない値を指定すると、カーソルは表示される。0 を指定すると、カーソルは隠蔽される。

戻り値

呼び出し前にカーソルが表示されていたかどうかを示す値。この値は、カーソルが表示されていた場合は 0 以外の値、表示されていなかった場合は 0 である。

エラー コード

失敗した場合はエラーが発生し、Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

このメソッドは、Microsoft® Win32® API の ShowCursor および SetCursor 関数とは独立している。アプリケーションでは、Win32 カーソルまたは Microsoft Direct3D® カーソルのいずれかを使用し、両方を使用してはならない。

参照

Direct3DDevice8.SetCursorPosition、Direct3DDevice8.SetCursorProperties


Direct3DDevice8.TestCooperativeLevel

ウィンドウ アプリケーションまたはフルスクリーン アプリケーションに対する Microsoft® Direct3D® デバイスの現在の協調レベル ステータスを報告する。

object.TestCooperativeLevel() As Long

指定項目

object
Direct3DDevice8 オブジェクトを表すオブジェクト式。

戻り値

成功した場合は D3D_OK を返す。この戻り値は、デバイスが動作しており、呼び出し側アプリケーションが実行を継続できることを示している。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される (「注意」を参照)。

D3DERR_DEVICELOST
D3DERR_DEVICENOTRESET

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

デバイスが失われたにもかかわらず現時点では復元できない場合、Direct3DDevice8.TestCooperativeLevel は D3DERR_DEVICELOST リターン コードを返す。たとえば、フルスクリーン デバイスがフォーカスを失ったような場合である。アプリケーションで消失したデバイスを検出した場合、アプリケーションは一時停止して TestCooperativeLevel を定期的に呼び出し、戻り値 D3DERR_DEVICENOTRESET を受け取るまで待機する必要がある。その後で、Direct3DDevice8.Reset を呼び出してデバイスをリセットする。これに成功した場合は、必要なリソースを復元し、通常の処理を再開する。デバイスの状態が "消失" または "非リセット" のいずれかの場合は、Direct3DDevice8.Present は D3DERR_DEVICELOST を返すことに注意する。


Direct3DDevice8.UpdateTexture

テクスチャのダーティー部分を更新する。

object.UpdateTexture( _
    SourceTexture As Direct3DBaseTexture8, _
    DestinationTexture As Direct3DBaseTexture8)

指定項目

object
Direct3DDevice8 オブジェクトを表すオブジェクト式。
SourceTexture
転送元テクスチャを表す Direct3DBaseTexture8 オブジェクト。転送元テクスチャはシステム メモリ内 (D3DPOOL_SYSTEMMEM) になければならない。
DestinationTexture
転送先テクスチャを表す Direct3DBaseTexture8 オブジェクト。転送先テクスチャは D3DPOOL_DEFAULT メモリ プールになければならない。

エラー コード

失敗した場合はエラーが発生し、Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

テクスチャの一部分をダーティーにするには、その部分をロックするか、または次のいずれかのメソッドを呼び出す。

  • Direct3DCubeTexture8.AddDirtyRect
  • Direct3DTexture8.AddDirtyRect
  • Direct3DVolumeTexture8.AddDirtyBox
  • Direct3DDevice8.CopyRects

UpdateTexture は、最後の更新処理以降に蓄積された処理を計算することで、テクスチャのダーティー部分を取得する。

転送元と転送先のテクスチャのタイプが異なる場合、両方のテクスチャの最下位バッファのサイズが異なる場合、および一致レベルが一致しない場合、このメソッドは失敗する。たとえば、次のようなディメンジョンの 6 つのレベルの転送元テクスチャがあるとする。

32x16, 16x8, 8x4, 4x2, 2x1, 1x1

この 6 つのレベルの転送元テクスチャは、次の 1 つのレベルの転送先の転送元になる。

1x1

2 つのレベルの転送先の場合。

2x1, 1x1

または、3 つのレベルの転送先の場合。

4x2, 2x1, 1x1

また、テクスチャのフォーマットが異なる場合、このメソッドは失敗する。転送先テクスチャのレベル数が転送元より少ない場合は、一致するレベルだけがコピーされる。

転送元テクスチャにダーティー領域がある場合は、コピーをその領域だけに限定することで、コピー処理を最適化できる。ダーティーとしてマークされているバイトだけがコピーされる保証はない。

パフォーマンスの理由によって、ダーティーな範囲はテクスチャのレベルゼロに対して記録されるのみである。サブレベルについては、対応する (スケールされた) 矩形またはボックスもダーティーであると仮定される。D3DLOCK_NO_DIRTY_UPDATE または D3DLOCK_READONLY なしで LockRect か LockBox が呼び出されたとき、ダーティーな範囲は自動的に記録される。また CopyRects 呼び出しの宛先サーフェスはダーティーとしてマークされる。


Direct3DDevice8.ValidateDevice

現在のテクスチャのブレンディング処理と引数をデバイスが 1 回の処理でレンダリングできる能力を報告する。

object.ValidateDevice() As Long

指定項目

object
Direct3DDevice8 オブジェクトを表すオブジェクト式。

戻り値

成功した場合は、マルチパス レンダリングによって目的のエフェクトを完成させるためのレンダリング パスの回数を返す。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_CONFLICTINGTEXTUREFILTER
D3DERR_CONFLICTINGTEXTUREPALETTE
D3DERR_TOOMANYOPERATIONS
D3DERR_UNSUPPORTEDALPHAARG
D3DERR_UNSUPPORTEDALPHAOPERATION
D3DERR_UNSUPPORTEDCOLORARG
D3DERR_UNSUPPORTEDCOLOROPERATION
D3DERR_UNSUPPORTEDFACTORVALUE
D3DERR_UNSUPPORTEDTEXTUREFILTER
D3DERR_WRONGTEXTUREFORMAT

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

ValidateDevice メソッドは、ほかの能力が不十分なシナリオを検証するためにのみ使用しなければならない。たとえば、マルチステージ テクスチャリングのシナリオでは、D3DCAPS8 型の MaxTextureBlendStages メンバと MaxSimultaneousTextures メンバを調べることで、そのデバイスでマルチステージ テクスチャリングが可能かどうかを判断できる。

現在のハードウェアが、必ずしも処理と引数の可能なすべての組み合わせを実装しているとは限らない。与えられた引数で特定のブレンディング処理を実行できるかどうかは、目的のブレンディング処理を設定し、ValidateDevice メソッドを呼び出すことにより確認できる。

ValidateDevice メソッドは、現在のレンダリング ステート、テクスチャ、テクスチャ ステージのステートを使って、呼び出された時点での確認を行う。この呼び出しの後でこれらの要素に変更があると、それまでの確認結果は無効になるので、シーンのレンダリングをする前にこのメソッドを再度呼び出さなければならない。

ディフューズ補間値の引数または処理 (D3DTA_DIFFUSE または D3DTOP_BLENDDIFFUSEALPHA) としての使用は、現在のハードウェアではほとんどサポートされていない。ほとんどのハードウェアでは、直前のテクスチャ処理ステージにおいて補間色データを導入している程度である。

各ステージのテクスチャ (D3DTA_TEXTURE) は、第 2 引数ではなく第 1 引数として指定するようにする。

多くのカードは、任意のテクスチャ ステージにおけるディフューズ値やスカラー値の使用はサポートしていない。これらは、最初または最後のテクスチャ ブレンディング ステージでのみ使用できることが多い。

最初のテクスチャに関連付けられたブレンディング ユニットで、アルファ チャネルからカラー チャネルへの複製や入力反転など以上の能力を持つものを備えたカードは少ない。したがって、アプリケーションでは、可能な場合、2 つ目のテクスチャ ステージのみを使用しなければならないときがある。このようなハードウェアでは、最初のユニットはデフォルト ステートにあると仮定され、D3DTOP_SELECTARG1 処理における第 1 カラー引数には D3DTA_TEXTURE が設定される。

出力されるアルファ値に対する処理で、カラー処理より複雑なもの、またはカラー処理と本質的に異なるものをサポートするハードウェアは、さらに少ない。

ハードウェアによっては、D3DTA_TFACTOR と D3DTA_DIFFUSE の同時使用をサポートしていない場合もある。

また多くのカードは、マルチ テクスチャとミップマップ トライリニア フィルタリングの同時使用をサポートしていない。マルチ テクスチャのブレンディング処理に関係するテクスチャに対してトライリニア フィルタリングを行う要求があり、確認が失敗した場合は、トライリニア フィルタリングをやめて再度確認を行う。このような場合には、代わりにマルチパス レンダリングを実行する必要がある。

参照

Direct3DDevice8.GetTextureStageState、Direct3DDevice8.SetTextureStageState


Direct3DIndexBuffer8

インデックス バッファ リソースを操作するには、Direct3DIndexBuffer8 クラスのメソッドを使用する。

Direct3DIndexBuffer8 クラスを取得するには、Direct3DDevice8.CreateIndexBuffer メソッドを呼び出す。

Direct3DIndexBuffer8 クラスは、次のようなグループに分類できる Direct3DResource8 メソッドを実装している。

デバイス | GetDevice
情報 | GetType
プライベート サーフェス データ | FreePrivateData
 | GetPrivateData
 | SetPrivateData
リソース管理 | GetPriority
 | PreLoad
 | SetPriority

Direct3DIndexBuffer8 クラスのメソッドは、以下のグループにまとめることができる。

情報 | GetDesc
ロック | Lock
 | Unlock

参照

Direct3DDevice8.CreateIndexBuffer


Direct3DIndexBuffer8.GetDesc

インデックス バッファ リソースの記述を取得する。

object.GetDesc( _
    Desc As D3DINDEXBUFFER_DESC)

指定項目

object
Direct3DIndexBuffer8 オブジェクトを表すオブジェクト式。
Desc
返されるインデックス バッファが記述されている D3DINDEXBUFFER_DESC 型。

エラー コード

失敗した場合はエラーが発生し、パラメータが無効の場合は Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。


Direct3DIndexBuffer8.Lock

インデックス データの範囲をロックし、インデックス バッファ メモリにアクセスする。

object.Lock( _
    OffsetToLock As Long, _
    SizeToLock As Long, _
    Data As Long, _
    Flags As Long)

指定項目

object
Direct3DIndexBuffer8 オブジェクトを表すオブジェクト式。
OffsetToLock
ロックするインデックス データへのオフセット (バイト単位)。
SizeToLock
ロックするインデックス データのサイズ (バイト単位)。
Data
返されるインデックス データが格納される Long 値配列の先頭要素。
Flags
CONST_D3DLOCKFLAGS 列挙で定義される有効なロッキング フラグの 0 個以上の組み合わせ。インデックス バッファ メモリをロックする方法を示す。

エラー コード

失敗した場合はエラーが発生し、Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

1 つの関数呼び出しでインデックス データのロック、読み取り、およびアンロックを行うには、D3DIndexBuffer8GetData を使用する。

1 つの関数呼び出しで書き込みロックし、インデックス データをアンロックするには、D3DIndexBuffer8SetData を使用する。

インデックス バッファを操作する場合、複数のロック呼び出しを行うことができる。ただし、ロック呼び出しの数とアンロック呼び出しの数は一致していなければならない。現在設定しているインデックス バッファでロック カウントが残っている場合、DrawPrimitive の呼び出しは失敗する。

D3DLOCK_DISCARD または D3DLOCK_NOOVERWRITE を Lock メソッドの Flags パラメータで使用する方法については、「動的な頂点およびインデックス バッファの使い方」を参照すること。

参照

Direct3DIndexBuffer8.Unlock、D3DIndexBuffer8GetData、D3DIndexBuffer8SetData


Direct3DIndexBuffer8.Unlock

インデックス データをアンロックする。

object.Unlock()

指定項目

object
Direct3DIndexBuffer8 オブジェクトを表すオブジェクト式。

エラー コード

失敗した場合はエラーが発生し、Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

1 つの関数呼び出しでインデックス データのロック、読み取り、およびアンロックを行うには、D3DIndexBuffer8GetData を使用する。

1 つの関数呼び出しで書き込みロックし、インデックス データをアンロックするには、D3DIndexBuffer8SetData を使用する。

参照

Direct3DIndexBuffer8.Lock、D3DIndexBuffer8SetData、D3DIndexBuffer8SetData


Direct3DResource8

リソースの照会および準備を行うには、Direct3DResource8 クラスのメソッドを使用する。

次のいずれかのメソッドを呼び出すことで、テクスチャ リソースを作成できる。

  • Direct3DDevice8.CreateCubeTexture
  • Direct3DDevice8.CreateTexture
  • Direct3DDevice8.CreateVolumeTexture

次のいずれかのメソッドを呼び出すことで、ジオメトリ指向のリソースを作成できる。

  • Direct3DDevice8.CreateIndexBuffer
  • Direct3DDevice8.CreateVertexBuffer

Direct3DResource8 クラスのメソッドは、以下のグループにまとめることができる。

デバイス | GetDevice
情報 | GetType
プライベート サーフェス データ | FreePrivateData
 | GetPrivateData
 | SetPrivateData
リソース管理 | GetPriority
 | PreLoad
 | SetPriority


Direct3DResource8.FreePrivateData

このリソースに関連付けられている指定されたプライベート データを解放する。

object.FreePrivateData( _
    RefGuid As DXGUID)

指定項目

object
Direct3DResource8 オブジェクトを表すオブジェクト式。
RefGuid
解放するプライベート データを識別するグローバル ユニーク識別子 (GUID)。DXGUID 型で指定する。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DERR_NOTFOUND

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

対象

このメソッドは次のクラスに適用される。これらのクラスは、Direct3DResource8 のメソッドを実装する。

  • Direct3DBaseTexture8
  • Direct3DCubeTexture8
  • Direct3DIndexBuffer8
  • Direct3DTexture8
  • Direct3DVertexBuffer8
  • Direct3DVolumeTexture8

参照

Direct3DResource8.GetPrivateData、Direct3DResource8.SetPrivateData


Direct3DResource8.GetDevice

リソースに関連付けられているデバイスを取得する。

object.GetDevice( _
    Riid As GUID) As Direct3DDevice8

指定項目

object
Direct3DResource8 オブジェクトを表すオブジェクト式。
Riid
要求するデバイスの参照識別子を示す GUID 型。

戻り値

照会が成功した場合に、デバイス オブジェクトを格納する Unknown オブジェクト。

エラー コード

失敗した場合はエラーが発生し、Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

対象

このメソッドは次のクラスに適用される。これらのクラスは、Direct3DResource8 のメソッドを実装する。

  • Direct3DBaseTexture8
  • Direct3DCubeTexture8
  • Direct3DIndexBuffer8
  • Direct3DTexture8
  • Direct3DVertexBuffer8
  • Direct3DVolumeTexture8


Direct3DResource8.GetPriority

このリソースの優先順位を取得する。

object.GetPriority() As Long

指定項目

object
Direct3DResource8 オブジェクトを表すオブジェクト式。

戻り値

リソースの優先順位を示す Long 値を返す。

エラー コード

失敗した場合はエラーが発生し、Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

対象

このメソッドは次のクラスに適用される。これらのクラスは、Direct3DResource8 のメソッドを実装する。

  • Direct3DBaseTexture8
  • Direct3DCubeTexture8
  • Direct3DIndexBuffer8
  • Direct3DTexture8
  • Direct3DVertexBuffer8
  • Direct3DVolumeTexture8

注意

GetPriority を使って、管理下のリソースの優先順位を制御する。管理下にないリソースに対しては 0 が返る。

優先順位を使用して、管理下のリソースをメモリからいつ削除するかを決定できる。優先順位が低いリソースは、優先順位が高いリソースより先に削除される。2 つのリソースの優先順位が同じ場合は、最終使用時が新しい方のリソースがメモリに保持され、もう一方のリソースが削除される。管理下のリソースのデフォルトの優先順位は 0 である。

参照

Direct3DResource8.SetPriority


Direct3DResource8.GetPrivateData

リソースに関連付けられたプライベート データを提供されたバッファにコピーする。

object.GetPrivateData( _
    RefGuid As DXGUID, _
    Data As Any, _
    SizeOfData As Long)

指定項目

object
Direct3DResource8 オブジェクトを表すオブジェクト式。
RefGuid
取得するプライベート データを識別するグローバル ユニーク識別子 (GUID)。DXGUID 型で指定する。
Data
呼び出しが成功した場合に、要求したプライベート データを格納する割り当て済みバッファ。このメソッドを呼び出すアプリケーションは、このバッファの割り当てと解放に責任を負う。
SizeOfData
Data のバッファ サイズ (バイト単位)。この値が実際のプライベート データのサイズより小さい (0 など) 場合、メソッドは必要なバッファ サイズをこのパラメータに設定し、D3DERR_MOREDATA を返す。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DERR_MOREDATA
D3DERR_NOTFOUND

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

対象

このメソッドは次のクラスに適用される。これらのクラスは、Direct3DResource8 のメソッドを実装する。

  • Direct3DBaseTexture8
  • Direct3DCubeTexture8
  • Direct3DIndexBuffer8
  • Direct3DTexture8
  • Direct3DVertexBuffer8
  • Direct3DVolumeTexture8

参照

Direct3DResource8.FreePrivateData、Direct3DResource8.SetPrivateData


Direct3DResource8.GetType

リソースのタイプを返す。

object.GetType() As CONST_D3DRESOURCETYPE

指定項目

object
Direct3DResource8 オブジェクトを表すオブジェクト式。

戻り値

リソースのタイプを示す CONST_D3DRESOURCETYPE 列挙のメンバを返す。

エラー コード

失敗した場合はエラーが発生し、Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

対象

このメソッドは次のクラスに適用される。これらのクラスは、Direct3DResource8 のメソッドを実装する。

  • Direct3DBaseTexture8
  • Direct3DCubeTexture8
  • Direct3DIndexBuffer8
  • Direct3DTexture8
  • Direct3DVertexBuffer8
  • Direct3DVolumeTexture8


Direct3DResource8.PreLoad

管理下のリソースをプリロードする。

object.PreLoad()

指定項目

object
Direct3DResource8 オブジェクトを表すオブジェクト式。

エラー コード

失敗した場合はエラーが発生し、Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

対象

このメソッドは次のクラスに適用される。これらのクラスは、Direct3DResource8 のメソッドを実装する。

  • Direct3DBaseTexture8
  • Direct3DCubeTexture8
  • Direct3DIndexBuffer8
  • Direct3DTexture8
  • Direct3DVertexBuffer8
  • Direct3DVolumeTexture8

注意

このメソッドを呼び出すことは、この管理下のリソースがアプリケーションにおいて間もなく必要になることを意味する。管理下にないリソースに対してはどのような影響も及ぼさない。

PreLoad は、各フレームで使用するリソースが、ビデオ メモリ内に同時に収容できる量を超えている "スラッシング" 状態を検出する。そのような状況下では、Preload は何も処理を行わない。


Direct3DResource8.SetPriority

このリソースにリソース管理の優先順位を割り当てる。

object.SetPriority( _
    PriorityNew As Long) As Long

指定項目

object
Direct3DResource8 オブジェクトを表すオブジェクト式。
PriorityNew
リソースに対する新しいリソース管理優先順位を示す Long 値。

戻り値

以前リソースに割り当てられていた優先順位の値を返す。

エラー コード

失敗した場合はエラーが発生し、Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

対象

このメソッドは次のクラスに適用される。これらのクラスは、Direct3DResource8 のメソッドを実装する。

  • Direct3DBaseTexture8
  • Direct3DCubeTexture8
  • Direct3DIndexBuffer8
  • Direct3DTexture8
  • Direct3DVertexBuffer8
  • Direct3DVolumeTexture8

注意

SetPriority を使って、管理下のリソースの優先順位を制御する。管理下にないリソースに対しては 0 が返る。

優先順位を使用して、管理下のリソースをメモリからいつ削除するかを決定できる。優先順位が低いリソースは、優先順位が高いリソースより先に削除される。2 つのリソースの優先順位が同じ場合は、最終使用時が新しい方のリソースがメモリに保持され、もう一方のリソースが削除される。管理下のリソースのデフォルトの優先順位は 0 である。

参照

Direct3DResource8.GetPriority


Direct3DResource8.SetPrivateData

Microsoft® Direct3D® ではなく、アプリケーションでの使用が意図されているリソースとデータを関連付ける。データは値で渡され、複数のデータ セットを単一のリソースと関連付けることができる。

object.SetPrivateData( _
    RefGuid As DXGUID, _
    Data As Any, _
    SizeOfData As Long, _
    Flags As Long)

指定項目

object
Direct3DResource8 オブジェクトを表すオブジェクト式。
RefGuid
設定するプライベート データを識別するグローバル ユニーク識別子 (GUID)。DXGUID 型で指定する。
Data
リソースに関連付けられるデータを含むバッファ。
SizeOfData
Data のバッファ サイズ (バイト単位)。
Flags
渡されるデータ型を記述する値、またはリソースが変更された場合にデータを無効にする必要があることをアプリケーションに示す値。このパラメータには、CONST_D3DSPDFLAGS 列挙で定義されている値または 0 を指定できる。フラグを指定しない場合、Direct3D はメモリを割り当ててバッファ内のデータを保持し、新しいバッファにデータをコピーする。Direct3D によって割り当てられるバッファは、適宜自動的に解放される。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
E_OUTOFMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

対象

このメソッドは次のクラスに適用される。これらのクラスは、Direct3DResource8 のメソッドを実装する。

  • Direct3DBaseTexture8
  • Direct3DCubeTexture8
  • Direct3DIndexBuffer8
  • Direct3DTexture8
  • Direct3DVertexBuffer8
  • Direct3DVolumeTexture8

注意

Direct3D は Data でメモリを管理しない。このバッファを動的に割り当てた場合は、呼び出し側の責任でメモリを解放する。

参照

Direct3DResource8.FreePrivateData、Direct3DResource8.GetPrivateData


Direct3DSurface8

サーフェスの照会および準備を行うには、Direct3DSurface8 クラスのメソッドを使用する。

Direct3DSurface8 クラスのメソッドは、以下のグループにまとめることができる。

デバイス | GetDevice
情報 | GetContainer
 | GetDesc
サーフェスのロック | LockRect
 | UnlockRect
プライベート サーフェス データ | FreePrivateData
 | GetPrivateData
 | SetPrivateData

参照

サーフェス インターフェイス


Direct3DSurface8.FreePrivateData

このサーフェスに関連付けられている指定されたプライベート データを解放する。

object.FreePrivateData( _
    RefGuid As DXGUID)

指定項目

object
Direct3DSurface8 オブジェクトを表すオブジェクト式。
RefGuid
解放するプライベート データを識別するグローバル ユニーク識別子 (GUID)。DXGUID 型で指定する。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DERR_NOTFOUND

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

参照

Direct3DSurface8.GetPrivateData、Direct3DSurface8.SetPrivateData


Direct3DSurface8.GetContainer

このサーフェスがキューブ テクスチャまたはミップマップの子レベルである場合、親のキューブ テクスチャまたはテクスチャ (ミップマップ) オブジェクトへのアクセスを提供する。

object.GetContainer( _
    Riid  As GUID) As Unknown

指定項目

object
Direct3DSurface8 オブジェクトを表すオブジェクト式。
Riid
要求されるコンテナの参照識別子。

戻り値

照会が成功した場合に、コンテナ オブジェクトを格納する Unknown オブジェクト。「注意」を参照すること。

エラー コード

失敗した場合はエラーが発生し、Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

サーフェスが Direct3DDevice8.CreateImageSurface、Direct3Ddevice8.CreateRenderTarget、または Direct3DDevice8.CreateDepthStencilSurface を使って作成されている場合、サーフェスはスタンドアロンであると見なされる。この場合、GetContainer は、サーフェスの作成に使用した Direct3D デバイスを返す。


Direct3DSurface8.GetDesc

サーフェスの記述を取得する。

object.GetDesc( _
    Desc As D3DSURFACE_DESC)

指定項目

object
Direct3DSurface8 オブジェクトを表すオブジェクト式。
Desc
サーフェスが記述されている D3DSURFACE_DESC 型。

エラー コード

失敗した場合はエラーが発生し、Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。


Direct3DSurface8.GetDevice

サーフェスに関連付けられているデバイスを取得する。

object.GetDevice() As Direct3DDevice8

指定項目

object
Direct3DSurface8 オブジェクトを表すオブジェクト式。

戻り値

照会が成功した場合、サーフェスに関連付けられた Direct3DDevice8。

エラー コード

失敗した場合はエラーが発生し、Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

このメソッドを使用すると、所有しているデバイス オブジェクトに移動できる。


Direct3DSurface8.GetPrivateData

サーフェスに関連付けられたプライベート データを提供されたバッファにコピーする。

object.GetPrivateData( _
    RefGuid As DXGUID, _
    Data As Any, _
    SizeOfData As Long)

指定項目

object
Direct3DSurface8 オブジェクトを表すオブジェクト式。
RefGuid
取得するプライベート データを識別するグローバル ユニーク識別子 (GUID)。DXGUID 型で指定する。
Data
呼び出しが成功した場合に、要求したプライベート データを格納する割り当て済みバッファ。このメソッドを呼び出すアプリケーションは、このバッファの割り当てと解放に責任を負う。
SizeOfData
Data のバッファ サイズ (バイト単位)。この値が実際のプライベート データのサイズより小さい (0 など) 場合、メソッドは必要なバッファ サイズをこのパラメータに設定し、D3DERR_MOREDATA を返す。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DERR_MOREDATA
D3DERR_NOTFOUND

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

参照

Direct3DSurface8.FreePrivateData、Direct3DSurface8.SetPrivateData


Direct3DSurface8.LockRect

サーフェス上の矩形をロックする。

object.LockRect( _
    LockedRect As D3DLOCKED_RECT, _
    RECT As Any, _
    Flags As Long)

指定項目

object
Direct3DSurface8 オブジェクトを表すオブジェクト式。
LockedRect
ロックされた領域を記述する D3DLOCKED_RECT 型。
RECT
ロックする矩形。RECT 型によって指定される。または、ByVal 0 の場合はサーフェス全体を覆うようにダーティー領域が拡大する。
Flags
実行するロックの種類を記述する CONST_D3DLOCKFLAGS 列挙によって定義される 0 個以上の有効なロッキング フラグの組み合わせ。

エラー コード

失敗した場合はエラーが発生し、Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

マルチサンプル バック バッファはロックできない。

パフォーマンスの理由によって、ダーティーな範囲はテクスチャのレベルゼロに対して記録されるのみである。D3DLOCK_NO_DIRTY_UPDATE または D3DLOCK_READONLY なしで LockRect か LockBox が呼び出されたとき、ダーティーな範囲は自動的に記録される。詳細については、「Direct3DDevice8.UpdateTexture」を参照すること。

参照

Direct3DSurface8.UnlockRect


Direct3DSurface8.SetPrivateData

Microsoft® Direct3D® ではなく、アプリケーションでの使用が意図されているサーフェスとデータを関連付ける。

object.SetPrivateData( _
    RefGuid As DXGUID, _
    Data As Any, _
    SizeOfData As Long, _
    Flags As Long)

指定項目

object
Direct3DSurface8 オブジェクトを表すオブジェクト式。
RefGuid
設定するプライベート データを識別するグローバル ユニーク識別子 (GUID)。DXGUID 型で指定する。
Data
サーフェスと関連付けるデータが格納されているバッファ。
SizeOfData
Data のバッファ サイズ (バイト単位)。
Flags
渡されるデータ型を記述する値、またはリソースが変更された場合にデータを無効にする必要があることをアプリケーションに示す値。このパラメータには、CONST_D3DSPDFLAGS 列挙で定義されている値または 0 を指定できる。フラグを指定しない場合、Direct3D はメモリを割り当ててバッファ内のデータを保持し、新しいバッファにデータをコピーする。Direct3D によって割り当てられるバッファは、適宜自動的に解放される。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
E_OUTOFMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

Direct3D は Data でメモリを管理しない。このバッファを動的に割り当てた場合は、呼び出し側の責任でメモリを解放する。

データは値で渡され、複数のデータ セットを単一のサーフェスと関連付けることができる。

参照

Direct3DSurface8.FreePrivateData、Direct3DSurface8.GetPrivateData


Direct3DSurface8.UnlockRect

サーフェス上の矩形をアンロックする。

object.UnlockRect()

指定項目

object
Direct3DSurface8 オブジェクトを表すオブジェクト式。

エラー コード

失敗した場合はエラーが発生し、Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

参照

Direct3DSurface8.LockRect


Direct3DSwapChain8

スワップ チェーンを操作するには、Direct3DSwapChain8 クラスのメソッドを使用する。

各デバイスには、少なくとも 1 つのスワップ チェーンが常に存在しており、非明示的なスワップ チェーンと呼ばれる。ただし、Direct3DDevice8.CreateAdditionalSwapChain メソッドを呼び出して追加スワップ チェーンを作成すれば、同じデバイスから複数のビューをレンダリングすることができる。

Direct3DSwapChain8 クラスのメソッドは、以下のグループにまとめることができる。

プレゼンテーション | Present
サーフェス管理 | GetBackBuffer

参照

Direct3DDevice8.CreateAdditionalSwapChain


Direct3DSwapChain8.GetBackBuffer

デバイスのスワップ チェーンからバック バッファを取得する。

object.GetBackBuffer( _
    BackBuffer As Long, _
    BufferType As CONST_D3DBACKBUFFERTYPE) As Direct3DSurface8

指定項目

object
Direct3DSwapChain8 オブジェクトを表すオブジェクト式。
BackBuffer
返すバック バッファ オブジェクトのインデックス。バック バッファは 0 からバック バッファの総数 -1 までナンバリングされる。0 の戻り値は最初のバック バッファを示し、フロント バッファではない。このメソッドを使用してフロント バッファにアクセスすることはできない。
BufferType
DirectX 8.0 ではステレオ ビューはサポートされていないので、このパラメータの有効な値は D3DBACKBUFFER_TYPE_MONO だけである。

戻り値

返されたバック バッファのサーフェスを表す Direct3DSurface8 オブジェクト。

エラー コード

BackBuffer がバック バッファの総数以上の場合、エラーが発生し、Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。


Direct3DSwapChain8.Present

スワップ チェーンが所有するバック バッファのシーケンスから次のコンテンツを提示する。

object.Present( _
    SourceRect As Any, _
    DestRect As Any, _
    DestWindowOverride As Long, _
    DirtyRegion As Any)

指定項目

object
Direct3DSwapChain8 オブジェクトを表すオブジェクト式。
SourceRect
スワップ チェーンが D3DSWAPEFFECT_COPY または D3DSWAPEFFECT_COPY_VSYNC で作成されていない限り、値は ByVal 0 である必要がある。SourceRect は転送元矩形を含む型である。ByVal が 0 の場合、転送元サーフェス全体が表示される。矩形が転送元サーフェスを超えた場合、矩形は転送元サーフェスにクリッピングされる。
DestRect
スワップ チェーンが D3DSWAPEFFECT_COPY または D3DSWAPEFFECT_COPY_VSYNC で作成されていない限り、値は ByVal 0 である必要がある。DestRect は、ウィンドウのクライアント座標に転送先矩形を含む型である。ByVal が 0 の場合は、クライアント領域全体が格納される。矩形が転送先のクライアント領域を越えた場合、矩形は転送先のクライアント領域にクリッピングされる。
DestWindowOverride
クライアント領域がこのプレゼンテーションの対象として扱われる転送先ウィンドウ。
DirtyRegion
このパラメータは使用されず、ByVal 0 に設定する必要がある。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DERR_OUTOFVIDEOMEMORY
E_OUTOFMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

必要に応じて、転送元矩形内のピクセルをターゲット ウィンドウのクライアント領域の転送先矩形に転送するために拡大処理が適用される。

次のコードは、デフォルトの場合に Present を呼び出す方法を示している。

Dim swapChain As Direct3DSwapChain8
swapChain.Present ByVal 0, ByVal 0, 0, ByVal 0

デフォルトの場合、Any 型をとるパラメータには ByVal 0 を指定する必要があることに注意すること。Any 型のパラメータに 0 (ゼロ) を指定した場合は、エラーが発生し、メソッドは失敗する。

参照

Direct3DDevice8.Reset


Direct3DTexture8

テクスチャ リソースを操作するには、Direct3DTexture8 クラスのメソッドを使う。

Direct3DTexture8 クラスを取得するには、Direct3DDevice8.CreateTexture メソッドを呼び出す。

Direct3DTexture8 クラスは、次のようなグループに分類できる Direct3DResource8 メソッドを実装している。

デバイス | GetDevice
情報 | GetType
プライベート サーフェス データ | FreePrivateData
 | GetPrivateData
 | SetPrivateData
リソース管理 | GetPriority
 | PreLoad
 | SetPriority

Direct3DTexture8 クラスは、次のようなグループに分類できる Direct3DBaseTexture8 メソッドを実装している。

詳細 | GetLOD
 | SetLOD
情報 | GetLevelCount

Direct3DTexture8 クラスのメソッドは、以下のグループにまとめることができる。

情報 | GetLevelDesc
サーフェスのロック | LockRect
 | UnlockRect
その他 | AddDirtyRect
 | GetSurfaceLevel

参照

Direct3DDevice8.CreateTexture


Direct3DTexture8.AddDirtyRect

テクスチャ リソースにダーティー領域を追加する。

object.AddDirtyRect( _
    DirtyRect As Any)

指定項目

object
Direct3DTexture8 オブジェクトを表すオブジェクト式。
DirtyRect
RECT 型。追加するダーティー領域を指定する。ByVal 0 を指定すると、ダーティー領域が拡大してテクスチャ全体を覆う。

エラー コード

失敗した場合はエラーが発生し、Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

リソースのダーティー領域を指定することで、コピーされるリソースのサブセットを最適化できる。

パフォーマンスの理由によって、ダーティーな範囲はテクスチャのレベルゼロに対して記録されるのみである。サブレベルについては、対応する (スケールされた) 矩形またはボックスもダーティーであると仮定される。D3DLOCK_NO_DIRTY_UPDATE または D3DLOCK_READONLY なしで LockRect か LockBox が呼び出されたとき、ダーティーな範囲は自動的に記録される。また CopyRects 呼び出しの宛先サーフェスはダーティーとしてマークされる。


Direct3DTexture8.GetLevelDesc

テクスチャ サーフェスのレベル記述を取得する。

object.GetLevelDesc( _
    Level As Long, _
    Desc As D3DSURFACE_DESC)

指定項目

object
Direct3DTexture8 オブジェクトを表すオブジェクト式。
Level
テクスチャのリソースのレベルを識別する。このメソッドは、このパラメータで指定されたレベルに対するサーフェスの記述を返す。
Desc
返されるサーフェスが記述されている D3DSURFACE_DESC 型。

エラー コード

失敗した場合はエラーが発生し、パラメータの 1 つ以上が無効な場合は、Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。


Direct3DTexture8.GetSurfaceLevel

指定されたテクスチャ サーフェスのレベルを取得する。

object.GetSurfaceLevel( _
    Level As Long) As Direct3DSurface8

指定項目

object
Direct3DTexture8 オブジェクトを表すオブジェクト式。
Level
テクスチャのリソースのレベルを識別する。このメソッドは、このパラメータで指定されたレベルに対するサーフェスを返す。トップレベルのサーフェスは 0 で示される。

戻り値

返されるサーフェスを表す Direct3DSurface8 オブジェクト。

エラー コード

失敗した場合はエラーが発生し、Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。


Direct3DTexture8.LockRect

テクスチャ リソース上の矩形をロックする。

object.LockRect( _
    Level As Long, _
    LockedRect As D3DLOCKED_RECT, _
    RECT As Any, _
    Flags As Long)

指定項目

object
Direct3DTexture8 オブジェクトを表すオブジェクト式。
Level
ロックするテクスチャ リソースのレベルを指定する。
LockedRect
ロックされた領域を記述する D3DLOCKED_RECT 型。
RECT
ロックする矩形。RECT 型によって指定される。または、ByVal 0 の場合はテクスチャ全体を覆うようにダーティー領域が拡大する。
Flags
実行するロックの種類を記述する CONST_D3DLOCKFLAGS 列挙によって定義される 0 個以上の有効なロッキング フラグの組み合わせ。

エラー コード

失敗した場合はエラーが発生し、Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

D3DPOOL_DEFAULT で作成されたテクスチャはロックできない。

深度ステンシル サーフェスのロック可能なフォーマットは、D3DFMT_D16_LOCKABLE だけである。

マルチサンプル バック バッファはロックできない。ビデオ メモリ テクスチャはロックできないが、Direct3Ddevice8.CopyRects または Direct3Ddevice8.UpdateTexture を呼び出して修正する必要がある。Microsoft® DirectX® 8.0 が認識しない、一部のドライバ独自のピクセル フォーマットは例外である。これらはロックできる。

パフォーマンスの理由によって、ダーティーな範囲はテクスチャのレベルゼロに対して記録されるのみである。D3DLOCK_NO_DIRTY_UPDATE または D3DLOCK_READONLY なしで LockRect か LockBox が呼び出されたとき、ダーティーな範囲は自動的に記録される。詳細については、「Direct3DDevice8.UpdateTexture」を参照すること。

参照

Direct3DTexture8.UnlockRect


Direct3DTexture8.UnlockRect

テクスチャ リソース上の矩形をアンロックする。

object.UnlockRect( _
    Level As Long)

指定項目

object
Direct3DTexture8 オブジェクトを表すオブジェクト式。
Level
アンロックするテクスチャ リソースのレベルを指定する。

エラー コード

失敗した場合はエラーが発生し、Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

参照

Direct3DTexture8.LockRect


Direct3DVertexBuffer8

頂点バッファ リソースを操作するには、Direct3DVertexBuffer8 クラスのメソッドを使用する。

Direct3DVertexBuffer8 クラスを取得するには、Direct3DDevice8.CreateVertexBuffer メソッドを呼び出す。

Direct3DVertexBuffer8 クラスは、次のようなグループに分類できる Direct3DResource8 メソッドを実装している。

デバイス | GetDevice
情報 | GetType
プライベート サーフェス データ | FreePrivateData
 | GetPrivateData
 | SetPrivateData
リソース管理 | GetPriority
 | PreLoad
 | SetPriority

Direct3DVertexBuffer8 クラスのメソッドは、以下のグループにまとめることができる。

情報 | GetDesc
ロック | Lock
 | Unlock

参照

Direct3DDevice8.CreateVertexBuffer


Direct3DVertexBuffer8.GetDesc

頂点バッファ リソースの記述を取得する。

object.GetDesc( _
    Desc As D3DVERTEXBUFFER_DESC)

指定項目

object
Direct3DVertexBuffer8 オブジェクトを表すオブジェクト式。
Desc
返される頂点バッファが記述されている D3DVERTEXBUFFER_DESC 型。

エラー コード

失敗した場合はエラーが発生し、パラメータが無効の場合は Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。


Direct3DVertexBuffer8.Lock

頂点データの範囲をロックし、頂点バッファ メモリへのアクセスを可能にする。

object.Lock( _
    OffsetToLock As Long, _
    SizeToLock As Long, _
    Data As Long, _
    Flags As Long)

指定項目

object
Direct3DVertexBuffer8 オブジェクトを表すオブジェクト式。
OffsetToLock
ロックする頂点データのオフセット (バイト単位)。
SizeToLock
ロックする頂点データのサイズ (バイト単位)。0 を指定すると、頂点バッファ全体がロックされる。
Data
返される頂点データが格納される Long 値配列の先頭要素。
Flags
CONST_D3DLOCKFLAGS 列挙で定義される有効なロッキング フラグの 0 個以上の組み合わせ。頂点バッファ メモリをロックする方法を示す。

エラー コード

失敗した場合はエラーが発生し、Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

1 つの関数呼び出しで頂点データのロック、読み取り、およびアンロックを行うには、D3DVertexBuffer8GetData を使用する。

1 つの関数呼び出しで書き込みロックし、頂点データをアンロックするには、D3DVertexBuffer8SetData を使用する。

頂点バッファを操作する場合、複数のロック呼び出しを行うことができる。ただし、ロック呼び出しの数とアンロック呼び出しの数は一致していなければならない。現在設定している頂点バッファでロック カウントが残っている場合、DrawPrimitive の呼び出しは失敗する。

D3DLOCK_DISCARD または D3DLOCK_NOOVERWRITE を Lock メソッドの Flags パラメータで使用する方法については、「動的な頂点およびインデックス バッファの使い方」を参照すること。

参照

Direct3DVertexBuffer8.Unlock、D3DVertexBuffer8GetData、D3DVertexBuffer8SetData


Direct3DVertexBuffer8.Unlock

頂点データをアンロックする。

object.Unlock()

指定項目

object
Direct3DVertexBuffer8 オブジェクトを表すオブジェクト式。

エラー コード

失敗した場合はエラーが発生し、Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

1 つの関数呼び出しで頂点データのロック、読み取り、およびアンロックを行うには、D3DVertexBuffer8GetData を使用する。

1 つの関数呼び出しで書き込みロックし、頂点データをアンロックするには、D3DVertexBuffer8SetData を使用する。

参照

Direct3DVertexBuffer8.Lock、D3DVertexBuffer8GetData、D3DVertexBuffer8SetData


Direct3DVolume8

ボリューム リソースを操作するには、Direct3DVolume8 クラスのメソッドを使用する。

Direct3DVolume8 クラスを取得するには、Direct3DVolumeTexture8.GetVolumeLevel メソッドを呼び出す。

Direct3DVolume8 クラスのメソッドは、以下のグループにまとめることができる。

デバイス | GetDevice
情報 | GetContainer
 | GetDesc
ボリュームのロック | LockBox
 | UnlockBox
プライベート ボリューム データ | FreePrivateData
 | GetPrivateData
 | SetPrivateData


Direct3DVolume8.FreePrivateData

このボリュームに関連付けられている指定されたプライベート データを解放する。

object.FreePrivateData( _
    RefGuid As DXGUID)

指定項目

object
Direct3DVolume8 オブジェクトを表すオブジェクト式。
RefGuid
解放するプライベート データを識別するグローバル ユニーク識別子 (GUID)。DXGUID 型で指定する。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DERR_NOTFOUND

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

参照

Direct3DVolume8.GetPrivateData、Direct3DVolume8.SetPrivateData


Direct3DVolume8.GetContainer

このサーフェスがボリューム テクスチャの子レベルである場合、親のボリューム テクスチャ オブジェクトへのアクセスを提供する。

object.GetContainer( _
    Riid  As GUID) As Unknown

指定項目

object
Direct3DVolume8 オブジェクトを表すオブジェクト式。
Riid
要求するボリュームの参照識別子。

戻り値

照会が成功した場合に、コンテナ オブジェクトを格納する Unknown オブジェクト。

エラー コード

失敗した場合はエラーが発生し、Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。


Direct3DVolume8.GetDevice

ボリュームに関連付けられているデバイスを取得する。

object.GetDevice() As Direct3DDevice8

指定項目

object
Direct3DVolume8 オブジェクトを表すオブジェクト式。

戻り値

照会が成功した場合、ボリュームに関連付けられた Direct3DDevice8。

エラー コード

失敗した場合はエラーが発生し、Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

このメソッドを使用すると、所有しているデバイス オブジェクトに移動できる。たとえば、IID_IDirect3DDevice8 を使用すると、このバッファを作成したオブジェクトの Microsoft® Direct3D® インターフェイスが返される。


Direct3DVolume8.GetPrivateData

ボリュームに関連付けられたプライベート データを提供されたバッファにコピーする。

object.GetPrivateData( _
    RefGuid As DXGUID, _
    Data As Any, _
    SizeOfData As Long)

指定項目

object
Direct3DVolume8 オブジェクトを表すオブジェクト式。
RefGuid
取得するプライベート データを識別するグローバル ユニーク識別子 (GUID)。DXGUID 型で指定する。
Data
呼び出しが成功した場合に、要求したプライベート データを格納する割り当て済みバッファ。このメソッドを呼び出すアプリケーションは、このバッファの割り当てと解放に責任を負う。
SizeOfData
Data のバッファ サイズ (バイト単位)。この値が実際のプライベート データのサイズより小さい (0 など) 場合、メソッドは必要なバッファ サイズをこのパラメータに設定し、D3DERR_MOREDATA を返す。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DERR_MOREDATA
D3DERR_NOTFOUND

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

参照

Direct3DVolume8.FreePrivateData、Direct3DVolume8.SetPrivateData


Direct3DVolume8.GetDesc

ボリュームの記述を取得する。

object.GetDesc( _
    Desc As D3DVOLUME_DESC)

指定項目

object
Direct3DVolume8 オブジェクトを表すオブジェクト式。
Desc
ボリュームが記述されている D3DVOLUME_DESC 型。

エラー コード

失敗した場合はエラーが発生し、パラメータが無効の場合は Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。


Direct3DVolume8.LockBox

ボリュームのボックスをロックする。

object.LockBox( _
    LockedBox As D3DLOCKED_BOX, _
    Box As D3DBOX, _
    Flags As Long)

指定項目

object
Direct3DVolume8 オブジェクトを表すオブジェクト式。
LockedBox
ロックされた領域を記述する D3DLOCKED_BOX 型。
Box
ロックするボックス。D3DBOX 型を指定する。ByVal 0 を指定すると、ボリューム全体がロックされる。
Flags
実行するロックの種類を記述する CONST_D3DLOCKFLAGS 列挙によって定義される 0 個以上の有効なロッキング フラグの組み合わせ。

エラー コード

失敗した場合はエラーが発生し、Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

パフォーマンスの理由によって、ダーティーな範囲はテクスチャのレベルゼロに対して記録されるのみである。D3DLOCK_NO_DIRTY_UPDATE または D3DLOCK_READONLY なしで LockRect か LockBox が呼び出されたとき、ダーティーな範囲は自動的に記録される。詳細については、「Direct3DDevice8.UpdateTexture」を参照すること。

参照

Direct3DVolume8.UnlockBox


Direct3DVolume8.SetPrivateData

Microsoft® Direct3D® ではなく、アプリケーションでの使用が意図されているボリュームとデータを関連付ける。

object.SetPrivateData( _
    RefGuid As DXGUID, _
    Data As Any, _
    SizeOfData As Long, _
    Flags As Long)

指定項目

object
Direct3DVolume8 オブジェクトを表すオブジェクト式。
RefGuid
設定するプライベート データを識別するグローバル ユニーク識別子 (GUID)。DXGUID 型で指定する。
Data
サーフェスと関連付けるデータが格納されているバッファ。
SizeOfData
Data のバッファ サイズ (バイト単位)。
Flags
渡されるデータ型を記述する値、またはリソースが変更された場合にデータを無効にする必要があることをアプリケーションに示す値。このパラメータには、CONST_D3DSPDFLAGS 列挙で定義されている値または 0 を指定できる。フラグを指定しない場合、Direct3D はメモリを割り当ててバッファ内のデータを保持し、新しいバッファにデータをコピーする。Direct3D によって割り当てられるバッファは、適宜自動的に解放される。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
E_OUTOFMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

Direct3D は Data でメモリを管理しない。このバッファを動的に割り当てた場合は、呼び出し側の責任でメモリを解放する。

データは値で渡され、複数のデータ セットを単一のボリュームと関連付けることができる。

参照

Direct3DVolume8.FreePrivateData、Direct3DVolume8.GetPrivateData


Direct3DVolume8.UnlockBox

ボリュームのボックスをアンロックする。

object.UnlockBox()

指定項目

object
Direct3DVolume8 オブジェクトを表すオブジェクト式。

エラー コード

失敗した場合はエラーが発生し、Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

参照

Direct3DVolume8.LockBox


Direct3DVolumeTexture8

ボリューム テクスチャ リソースを操作するには、Direct3DVolumeTexture8 クラスのメソッドを使う。

Direct3DVolumeTexture8 クラスを取得するには、Direct3DDevice8.CreateVolumeTexture メソッドを呼び出す。

Direct3DVolumeTexture8 クラスは、次のようなグループに分類できる Direct3DResource8 メソッドを実装している。

デバイス | GetDevice
情報 | GetType
プライベート サーフェス データ | FreePrivateData
 | GetPrivateData
 | SetPrivateData
リソース管理 | GetPriority
 | PreLoad
 | SetPriority

Direct3DVolumeTexture8 クラスは、次のようなグループに分類できる Direct3DBaseTexture8 メソッドを実装している。

詳細 | GetLOD
 | SetLOD
情報 | GetLevelCount

Direct3DVolumeTexture8 クラスのメソッドは、以下のグループにまとめることができる。

情報 | GetLevelDesc
ボリュームのロック | LockBox
 | UnlockBox
その他 | AddDirtyBox
 | GetVolumeLevel

参照

Direct3DDevice8.CreateVolumeTexture


Direct3DVolumeTexture8.AddDirtyBox

ボリューム テクスチャ リソースにダーティー領域を追加する。

object.AddDirtyBox( _
    DirtyBox As Any)

指定項目

object
Direct3DVolumeTexture8 オブジェクトを表すオブジェクト式。
DirtyBox
D3DBOX 型。追加するダーティー領域を指定する。ByVal 0 を指定すると、ボリューム テクスチャ全体をロックする。

エラー コード

失敗した場合はエラーが発生し、Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

リソースのボックスを指定することで、コピーされるリソースのサブセットを最適化できる。ただし、ダーティー領域は、アラインメントを最適化するために拡大される場合がある。

パフォーマンスの理由によって、ダーティーな範囲はテクスチャのレベルゼロに対して記録されるのみである。サブレベルについては、対応する(スケールされた) 矩形またはボックスもダーティーであると仮定される。D3DLOCK_NO_DIRTY_UPDATE または D3DLOCK_READONLY なしで LockRect か LockBox が呼び出されたとき、ダーティーな範囲は自動的に記録される。また CopyRects 呼び出しの宛先サーフェスはダーティーとしてマークされる。


Direct3DVolumeTexture8.GetLevelDesc

ボリューム テクスチャ リソースのレベル記述を取得する。

object.GetLevelDesc( _
    Level As Long, _
    pDesc As D3DVOLUME_DESC)

指定項目

object
Direct3DVolumeTexture8 オブジェクトを表すオブジェクト式。
Level
ボリューム テクスチャ リソースのレベルを識別する。このメソッドは、このパラメータで指定されたレベルに対するボリューム記述を返す。
pDesc
返されるボリューム テクスチャ レベルが記述されている D3DVOLUME_DESC 型。

エラー コード

失敗した場合はエラーが発生し、パラメータの 1 つ以上が無効な場合は、Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。


Direct3DVolumeTexture8.GetVolumeLevel

指定されたボリューム テクスチャのレベルを取得する。

object.GetVolumeLevel( _
    Level As Long) As Direct3DVolume8

指定項目

object
Direct3DVolumeTexture8 オブジェクトを表すオブジェクト式。
Level
ボリューム テクスチャ リソースのレベルを識別する。このメソッドは、このパラメータで指定されているレベルに対するボリュームを返す。

戻り値

返されるボリューム レベルを表す Direct3DVolume8 オブジェクト。

エラー コード

失敗した場合はエラーが発生し、Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。


Direct3DVolumeTexture8.LockBox

ボリューム テクスチャ リソース上のボックスをロックする。

object.LockBox( _
    Level As Long, _
    LockedVolume As D3DLOCKED_BOX, _
    Box As Any, _
    Flags As Long)

指定項目

object
Direct3DVolumeTexture8 オブジェクトを表すオブジェクト式。
Level
ロックするボリューム テクスチャ リソースのレベルを指定する。
LockedVolume
ロックされた領域を記述する D3DLOCKED_BOX 型。
Box
ロックするボリューム。D3DBOX 型を指定する。ByVal 0 を指定すると、ボリューム レベル全体がロックされる。
Flags
実行するロックの種類を記述する CONST_D3DLOCKFLAGS 列挙によって定義される 0 個以上の有効なロッキング フラグの組み合わせ。

エラー コード

失敗した場合はエラーが発生し、Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

パフォーマンスの理由によって、ダーティーな範囲はテクスチャのレベル ゼロに対して記録されるのみである。D3DLOCK_NO_DIRTY_UPDATE または D3DLOCK_READONLY なしで LockRect か LockBox が呼び出されたとき、ダーティーな範囲は自動的に記録される。詳細については、「Direct3DDevice8.UpdateTexture」を参照すること。

参照

Direct3DVolumeTexture8.UnlockBox


Direct3DVolumeTexture8.UnlockBox

ボリューム テクスチャ リソース上のボックスをロックする。

object.UnlockBox( _
    Level As Long)

指定項目

object
Direct3DVolumeTexture8 オブジェクトを表すオブジェクト式。
Level
ロックするボリューム テクスチャ リソースのレベルを指定する。

エラー コード

失敗した場合はエラーが発生し、Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

参照

Direct3DVolumeTexture8.LockBox


関数

ここでは、Microsoft® Direct3D® を使用する場合に実装可能な関数のリファレンス情報を記述する。次の関数が実装されている。

  • D3DColorARGB
  • D3DColorMake
  • D3DColorRGBA
  • D3DColorXRGB
  • D3DIndexBuffer8GetData
  • D3DVertexBuffer8GetData
  • D3DIndexBuffer8SetData
  • D3DVertexBuffer8SetData


D3DColorARGB

指定されたアルファ、赤、緑、および青の各値で、色を初期化する。

D3DColorARGB( _
    a As Integer, _
    r As Integer, _
    g As Integer, _
    b As Integer) As Long

パラメータ

a
色のアルファ値。値の範囲は、0 ～ 255。
r
色の赤値。値の範囲は、0 ～ 255。
g
色の緑値。値の範囲は、0 ～ 255。
b
色の青値。値の範囲は、0 ～ 255。

戻り値

指定された ARGB 値に対応する Long 値を返す。

エラー コード

失敗した場合はエラーが発生し、Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Visual Basic の「エラー処理」を参照すること。


D3DColorMake

指定された赤、緑、青、およびアルファの各浮動小数点値で、色を初期化する。

D3DColorMake( _
    r As Single, _
    g As Single, _
    b As Single, _
    a As Single) As Long

パラメータ

r
色の赤値。値の範囲は、0.0 ～ 1.0。
g
色の緑値。値の範囲は、0.0 ～ 1.0。
b
色の青値。値の範囲は、0.0 ～ 1.0。
a
色のアルファ値。値の範囲は、0.0 ～ 1.0。

戻り値

指定された RGBA 値に対応する Long 値を返す。

エラー コード

失敗した場合はエラーが発生し、Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Visual Basic の「エラー処理」を参照すること。


D3DColorRGBA

指定された赤、緑、青、およびアルファの各値で、色を初期化する。

D3DColorRGBA( _
    a As Integer, _
    r As Integer, _
    g As Integer, _
    b As Integer) As Long

パラメータ

r
色の赤値。値の範囲は、0 ～ 255。
g
色の緑値。値の範囲は、0 ～ 255。
b
色の青値。値の範囲は、0 ～ 255。
a
色のアルファ値。値の範囲は、0 ～ 255。

戻り値

指定された RGBA 値に対応する Long 値を返す。

エラー コード

失敗した場合はエラーが発生し、Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Visual Basic の「エラー処理」を参照すること。


D3DColorXRGB

指定された赤、緑、および青の各値で、色を初期化する。

D3DColorXRGB( _
    r As Integer, _
    g As Integer, _
    b As Integer) As Long

パラメータ

r
色の赤値。値の範囲は、0 ～ 255。
g
色の緑値。値の範囲は、0 ～ 255。
b
色の青値。値の範囲は、0 ～ 255。

戻り値

指定された RGB 値に対応する Long 値を返す。

エラー コード

失敗した場合はエラーが発生し、Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Visual Basic の「エラー処理」を参照すること。


D3DIndexBuffer8GetData

インデックス バッファからデータを取得する。

D3DIndexBuffer8GetData( _
    IBuffer As Direct3DIndexBuffer8, _
    Offset As Long, _
    Size As Long, _
    Flags As Long, _
    Data As Any) As Long

パラメータ

IBuffer
データの取得先となるインデックス バッファを表す Direct3DIndexBuffer8 オブジェクト。
Offset
バッファの先頭からデータの取得開始位置までのオフセット (バイト単位)。
Size
バッファのサイズ (バイト単位)。
Flags
実行するロックのタイプを記述する、CONST_D3DLOCKFLAGS 列挙によって定義される 1 つ以上の有効なロッキング フラグの組み合わせ。
Data
取得されたデータを格納するバッファ。

戻り値

失敗した場合は、D3DERR_INVALIDCALL を返す。

エラー コード

この関数では、Err.Number は設定されない。

参照

D3DIndexBuffer8SetData


D3DVertexBuffer8GetData

頂点バッファからデータを取得する。

D3DVertexBuffer8GetData( _
    VBuffer As Direct3DVertexBuffer8, _
    Offset As Long, _
    Size As Long, _
    Flags As Long, _
    Data As Any) As Long

パラメータ

VBuffer
データの取得先となる頂点バッファを表す、Direct3DVertexBuffer8 オブジェクト。
Offset
バッファの先頭からデータの取得開始位置までのオフセット (バイト単位)。
Size
バッファのサイズ (バイト単位)。
Flags
実行するロックのタイプを記述する、CONST_D3DLOCKFLAGS 列挙によって定義される 1 つ以上の有効なロッキング フラグの組み合わせ。
Data
取得されたデータを格納するバッファ。

戻り値

失敗した場合は、D3DERR_INVALIDCALL を返す。

エラー コード

この関数では、Err.Number は設定されない。

参照

D3DVertexBuffer8SetData


D3DIndexBuffer8SetData

インデックス バッファ内にデータを設定する。

D3DIndexBuffer8SetData( _
    IBuffer As Direct3DIndexBuffer8, _
    Offset As Long, _
    Size As Long, _
    Flags As Long, _
    Data As Any) As Long

パラメータ

IBuffer
データを設定するインデックス バッファを表す Direct3DIndexBuffer8 オブジェクト。
Offset
バッファの先頭からデータが設定される位置までのオフセット (バイト単位)。
Size
バッファのサイズ (バイト単位)。
Flags
実行するロックのタイプを記述する、CONST_D3DLOCKFLAGS 列挙によって定義される 1 つ以上の有効なロッキング フラグの組み合わせ。
Data
設定するデータを格納するバッファ。

戻り値

失敗した場合は、D3DERR_INVALIDCALL を返す。

エラー コード

この関数では、Err.Number は設定されない。

参照

D3DIndexBuffer8GetData


D3DVertexBuffer8SetData

頂点バッファにデータを設定する。

D3DVertexBuffer8SetData( _
    VBuffer As Direct3DVertexBuffer8, _
    Offset As Long, _
    Size As Long, _
    Flags As Long, _
    Data As Any) As Long

パラメータ

VBuffer
データを設定する頂点バッファを表す、Direct3DVertexBuffer8 オブジェクト。
Offset
バッファの先頭からデータが設定される位置までのオフセット (バイト単位)。
Size
バッファのサイズ (バイト単位)。
Flags
実行するロックのタイプを記述する、CONST_D3DLOCKFLAGS 列挙によって定義される 1 つ以上の有効なロッキング フラグの組み合わせ。
Data
設定するデータを格納するバッファ。

戻り値

失敗した場合は、D3DERR_INVALIDCALL を返す。

エラー コード

この関数では、Err.Number は設定されない。

参照

D3DVertexBuffer8GetData


頂点シェーダ宣言子関数

ここでは、頂点シェーダ宣言配列を作成するビット アセンブリ関数について説明する。

  • D3DVSD_CONST
  • D3DVSD_END
  • D3DVSD_NOP
  • D3DVSD_REG
  • D3DVSD_SKIP
  • D3DVSD_STREAM
  • D3DVSD_STREAM_TESS
  • D3DVSD_TESSNORMAL
  • D3DVSD_TESSUV


D3DVSD_CONST

頂点シェーダ定数メモリにデータをロードする。

Function D3DVSD_CONST(ConstantAddress As Long, Count As Long) As Long
     D3DVSD_CONST = (D3DVSD_MAKETOKENTYPE(D3DVSD_TOKEN_constMEM) Or _
     ((Count) * 2 ^ D3DVSD_CONSTCOUNTSHIFT) Or (ConstantAddress))
End Function

パラメータ

ConstantAddress
データ格納を開始する定数配列のアドレス。使用できる値は 0 ～ 95。
Count
ロードされる定数ベクトルの数。「注意」を参照すること。

注意

D3DVSD_CONST および使用する定数はすべて (SDK ルート)\Samples\Multimedia\VBSamples\Common\D3DShaders.bas にある。

次のコードは、この関数の使用法を示している。

Dim Declarator(12) As Long

Declarator(0)  = D3DVSD_CONST(8, 1)
Declarator(1)  = FtoDW(1)
Declarator(2)  = FtoDW(1)
Declarator(3)  = FtoDW(1/255)
Declarator(4)  = FtoDW(1)
Declarator(5)  = D3DVSD_STREAM(0)
Declarator(6)  = D3DVSD_REG(0, D3DVSDT_FLOAT3)
Declarator(7)  = D3DVSD_REG(2, D3DVSDT_D3DCOLOR)
Declarator(8)  = D3DVSD_STREAM(1)
Declarator(9)  = D3DVSD_REG(1, D3DVSDT_FLOAT1)
Declarator(10) = D3DVSD_STREAM(2)
Declarator(11) = D3DVSD_REG(3, D3DVSDT_FLOAT2)
Declarator(12) = D3DVSD_END()

参照

Direct3DDevice8.CreateVertexShader


D3DVSD_END

END トークンを生成する。

Function D3DVSD_END() As Long
        D3DVSD_END = &HFFFFFFFF
End Function

パラメータ

なし。

注意

D3DVSD_END および使用する定数はすべて (SDK ルート)\Samples\Multimedia\VBSamples\Common\D3DShaders.bas にある。

参照

Direct3DDevice8.CreateVertexShader


D3DVSD_NOP

NOP トークンを生成する。

Function D3DVSD_NOP() As Long
    D3DVSD_NOP = 0
End Function

パラメータ

なし。

注意

D3DVSD_NOP および使用する定数はすべて (SDK ルート)\Samples\Multimedia\VBSamples\Common\D3DShaders.bas 内にある。

参照

Direct3DDevice8.CreateVertexShader


D3DVSD_REG

1 つの頂点レジスタを頂点ストリームの 1 つの頂点要素にバインドする。

Function D3DVSD_REG(VertexRegister As Long, dataType As Long) As Long
    D3DVSD_REG = (D3DVSD_MAKETOKENTYPE(D3DVSD_TOKEN_STREAMDATA) Or _
     ((dataType) * 2 ^ D3DVSD_DATATYPESHIFT) Or (VertexRegister))
End Function

パラメータ

VertexRegister
頂点レジスタのアドレス。使用できる値は 0 ～ 15。固定機能パイプラインの場合、入力レジスタには以下の固定マッピングがある。
D3DVSDE_POSITION
レジスタ 0。
D3DVSDE_BLENDWEIGHT
レジスタ 1。
D3DVSDE_NORMAL
レジスタ 2。
D3DVSDE_PSIZE
レジスタ 3。
D3DVSDE_DIFFUSE
レジスタ 4。
D3DVSDE_SPECULAR
レジスタ 5。
D3DVSDE_TEXCOORD0
レジスタ 6。
D3DVSDE_TEXCOORD1
レジスタ 7。
D3DVSDE_TEXCOORD2
レジスタ 8。
D3DVSDE_TEXCOORD3
レジスタ 9。
D3DVSDE_TEXCOORD4
レジスタ 10。
D3DVSDE_TEXCOORD5
レジスタ 11。
D3DVSDE_TEXCOORD6
レジスタ 12。
D3DVSDE_TEXCOORD7
レジスタ 13。
dataType
各ディメンジョンと演算データ型を指定する。以下の値が定義されている。
D3DVSDT_D3DCOLOR
0.0 ～ 1.0 の範囲にマップされる 4D パック済み符号なしバイト。ダブルワード形式ではこれは ARGBであり、バイト オーダーでは B、G、R、A である。
D3DVSDT_FLOAT1
(value, 0.0, 0.0, 1.0) に展開される 1D float。
D3DVSDT_FLOAT2
(value, value, 0.0, 1.0) に展開される 2D float。
D3DVSDT_FLOAT3
(value, value, value, 1.0) に展開される 3D float。
D3DVSDT_FLOAT4
4D float。
D3DVSDT_UBYTE4
4D 符号なしバイト。ダブルワード形式ではこれは ABGR、バイト オーダーでは R、G、B、A である。

注意

D3DVSD_REG およびすべての定数は (SDK ルート)\Samples\Multimedia\VBSamples\Common\D3DShaders.bas にある。

参照

Direct3DDevice8.CreateVertexShader


D3DVSD_SKIP

頂点内でスキップする Long の数を指定する。

Function D3DVSD_SKIP(LongCount As Long) As Long
    D3DVSD_SKIP = (D3DVSD_MAKETOKENTYPE(D3DVSD_TOKEN_STREAMDATA) Or _
                   &H10000000 Or _
                   ((LongCount) * 2 ^ D3DVSD_SKIPCOUNTSHIFT))
End Function

パラメータ

LongCount
頂点内でスキップする Long の数。

注意

D3DVSD_SKIP およびすべての定数は (SDK ルート)\Samples\Multimedia\VBSamples\Common\D3DShaders.bas にある。

参照

Direct3DDevice8.CreateVertexShader


D3DVSD_STREAM

カレント ストリームを設定する。

Function D3DVSD_STREAM(StreamNumber As Long) As Long
    D3DVSD_STREAM = (D3DVSD_MAKETOKENTYPE(D3DVSD_TOKEN_STREAM) Or _
                    (StreamNumber))
End Function

パラメータ

StreamNumber
データを取得するストリームを指定する。使用できる値は 0 ～ MaxStreams - 1。

注意

D3DVSD_STREAM およびすべての定数は (SDK ルート)\Samples\Multimedia\VBSamples\Common\D3DShaders.bas にある。

参照

Direct3DDevice8.CreateVertexShader


D3DVSD_STREAM_TESS

テッセレータ ストリームを設定する。

Function D3DVSD_STREAM_TESS() As Long
    D3DVSD_STREAM_TESS = (D3DVSD_MAKETOKENTYPE(D3DVSD_TOKEN_STREAM) Or _
                         (D3DVSD_STREAMTESSMASK))
End Function

パラメータ

なし。

注意

D3DVSD_STREAM_TESS およびすべての定数は (SDK ルート)\Samples\Multimedia\VBSamples\Common\D3DShaders.bas にある。

参照

Direct3DDevice8.CreateVertexShader


D3DVSD_TESSNORMAL

テッセレータによって生成された法線を有効にする。

Function D3DVSD_TESSNORMAL(VertexRegisterIn As Long, VertexRegisterOut As Long) As Long
    D3DVSD_TESSNORMAL = (D3DVSD_MAKETOKENTYPE(D3DVSD_TOKEN_TESSELLATOR) Or _
     ((VertexRegisterIn) * 2 ^ D3DVSD_VERTEXREGINSHIFT) Or _
     ((&H2&) * 2 ^ D3DVSD_DATATYPESHIFT) Or (VertexRegisterOut))
End Function

パラメータ

VertexRegisterIn
法線の計算に使用される入力ストリームを格納する頂点レジスタのアドレス。使用できる値は 0 ～ 15。
VertexRegisterOut
法線の出力先となる頂点レジスタのアドレス。使用できる値は 0 ～ 15。

注意

D3DVSD_TESSNORMAL およびすべての定数は (SDK ルート)\Samples\Multimedia\VBSamples\Common\D3DShaders.bas にある。

参照

Direct3DDevice8.CreateVertexShader


D3DVSD_TESSUV

テッセレータによって生成されたサーフェス パラメータを有効にする。

Function D3DVSD_TESSUV(VertexRegister As Long) As Long
    D3DVSD_TESSUV = (D3DVSD_MAKETOKENTYPE(D3DVSD_TOKEN_TESSELLATOR) Or _
                     &H10000000 Or _
                     ((&H1&) * 2 ^ D3DVSD_DATATYPESHIFT) Or _
                     (VertexRegister))
End Function

パラメータ

VertexRegister
パラメータの出力先となる頂点レジスタのアドレス。使用できる値は 0 ～ 15。

注意

D3DVSD_TESSUV およびすべての定数は (SDK ルート)\Samples\Multimedia\VBSamples\Common\D3DShaders.bas にある。

参照

Direct3DDevice8.CreateVertexShader


型

ここでは、Microsoft® Direct3D® で使用される以下の型について説明する。

  • D3DADAPTER_IDENTIFIER8
  • D3DBOX
  • D3DCAPS8
  • D3DCLIPSTATUS8
  • D3DCOLORVALUE
  • D3DDEVICE_CREATION_PARAMETERS
  • D3DDISPLAYMODE
  • D3DGAMMARAMP
  • D3DINDEXBUFFER_DESC
  • D3DLIGHT8
  • D3DLINEPATTERN
  • D3DLOCKED_BOX
  • D3DLOCKED_RECT
  • D3DLVERTEX
  • D3DLVERTEX2
  • D3DMATERIAL8
  • D3DMATRIX
  • D3DPLANE
  • D3DPRESENT_PARAMETERS
  • D3DQUATERNION
  • D3DRANGE
  • D3DRASTER_STATUS
  • D3DRECT
  • D3DRECTPATCH_INFO
  • D3DSURFACE_DESC
  • D3DTLVERTEX
  • D3DTLVERTEX2
  • D3DTRIPATCH_INFO
  • D3DVECTOR
  • D3DVECTOR2
  • D3DVECTOR4
  • D3DVERTEX
  • D3DVERTEX2
  • D3DVERTEXBUFFER_DESC
  • D3DVIEWPORT8
  • D3DVOLUME_DESC


D3DADAPTER_IDENTIFIER8

アダプタについての情報を保持する。

Type D3DADAPTER_IDENTIFIER8
    Description(0 To 511) As Byte
    DeviceId As Long
    DeviceIdentifier As DXGUID
    Driver(0 To 511) As Byte
    DriverVersionHighPart As Long
    DriverVersionLowPart As Long
    Revision As Long
    SubSysId As Long
    VendorId As Long
    WHQLLevel As Long
End Type

メンバ

Description および Driver
ユーザーに提示するために使用される。異なるベンダーから提供されている同種のデバイスおよびドライバに対して多くの異なる文字列が関連付けられている可能性があるため、特定のドライバを識別するためにこれらのメンバを使用すべきではない。
DeviceId
特定のチップ セットのタイプを識別する。不明な場合、この値は 0 になる場合がある。
DriverVersion、DriverVersionLowPart、および DriverVersionHighPart
Microsoft® Direct3D® ドライバのバージョンを識別する。Long 値に対して大小比較を行っても問題はない。ただし、この要素を使用して疑わしいドライバを識別する場合は、注意して行うこと。この値ではなく、DeviceIdentifier を使うことが望ましい。
DeviceIdentifier
グラフィックス サブシステムの新しいプロファイルを作成するために、ドライバおよびチップ セットへの変更を追跡する。DXGUID は、ドライバとチップ セットのペアに対する一意な識別子である。このメンバを使って、特定の疑わしいドライバを識別することもできる。
Revision
特定のチップ セットおよびリビジョン レベルを識別する。不明な場合、この値は 0 になる場合がある。
SubSysId
特定のチップ セットおよびサブシステムを識別する。通常、これはチップ セットのボードを意味する。不明な場合、この値は 0 になる場合がある。
VendorId
特定のチップ セットおよびそのメーカーを識別する。不明な場合、この値は 0 になる場合がある。
WHQLLevel
このデバイスとドライバのペアの Windows Hardware Quality Lab (WHQL) 認証レベルを特定する。Long にはパック形式のデータ構造が格納されており、ドライバが合格した最新の WHQL テストのリリース日が定義されている。この値に対して大小比較演算を行っても問題はない。以下は、日付のフォーマットを示している。
Bits
31-16:    The year, a decimal number from 1999 upwards.
15-8:     The month, a decimal number from 1 to 12.
7-0:      The day, a decimal number from 1 to 31.

次の値も使用される。

0
認証されていない。
1
WHQL の認証は受けているが、利用できる日付情報はない。

注意

VendorId、DeviceId、SubSysId、および Revision の各メンバを組み合わせて使うことで、特定のチップ セットを識別できる。ただし、これらのメンバを使うときは注意が必要である。


D3DBOX

ボリュームを定義する。

Type D3DBOX
    back As Long
    bottom As Long
    front As Long
    left As Long
    right As Long
    top As Long
End Type

メンバ

back、bottom、front、left、right、および top
ボックスのディメンジョン。

注意

D3DBOX には左側面、上面、および前面のエッジは含まれるが、右側面、底面、および背面のエッジは含まれない。たとえば、100 単位の幅で 0 から始まるボックス (つまり、最大 99 までのポイントを含む) は、0 という値の Left メンバと 100 という値の Right メンバで表される。Right メンバの値が 99 ではないことに注意すること。

D3DBOX で示される面の順序の規則は、左から右、上から下、および前から後である。


D3DCAPS8

Microsoft® Direct3D® オブジェクトが公開するハードウェアの能力を表す。

Type D3DCAPS8
    AdapterOrdinal As Long
    AlphaCmpCaps As Long
    caps As Long
    Caps2 As Long
    Caps3 As Long
    CubeTextureFilterCaps As Long
    CursorCaps As Long
    DestBlendCaps As Long
    DevCaps As Long
    DeviceType As Long
    ExtentsAdjust As Single
    FVFCaps As Long
    GuardBandBottom As Single
    GuardBandLeft As Single
    GuardBandRight As Single
    GuardBandTop As Single
    LineCaps As Long
    MaxActiveLights As Long
    MaxAnisotropy As Long
    MaxPixelShaderValue As Single
    MaxPointSize As Single
    MaxPrimitiveCount As Long
    MaxSimultaneousTextures As Long
    MaxStreams As Long
    MaxStreamStride As Long
    MaxTextureAspectRatio As Long
    MaxTextureBlendStages As Long
    MaxTextureHeight As Long
    MaxTextureRepeat As Long
    MaxTextureWidth As Long
    MaxUserClipPlanes As Long
    MaxVertexBlendMatrices As Long
    MaxVertexBlendMatrixIndex As Long
    MaxVertexIndex As Long
    MaxVertexShaderConst As Long
    MaxVertexW As Single
    MaxVolumeExtent As Long
    PixelShaderVersion As Long
    PresentationIntervals As Long
    PrimitiveMiscCaps As Long
    RasterCaps As Long
    ShadeCaps As Long
    SrcBlendCaps As Long
    StencilCaps As Long
    TextureAddressCaps As Long
    TextureCaps As Long
    TextureFilterCaps As Long
    TextureOpCaps As Long
    VertexProcessingCaps As Long
    VertexShaderVersion As Long
    VolumeTextureAddressCaps As Long
    VolumeTextureFilterCaps As Long
    ZCmpCaps As Long
End Type

メンバ

AdapterOrdinal
この Direct3DDevice オブジェクトが作成されたアダプタ。この序数は、この Direct3DDevice オブジェクトを作成した Direct3D8 クラスのメソッドに渡す場合にのみ有効である。Direct3D8 クラスは、常に、Direct3DDevice8.GetDirect3D を呼び出すことによって取得できる。
AlphaCmpCaps
アルファ テスト比較能力。このメンバが D3DPCMPCAPS_ALWAYS 能力だけ、または D3DPCMPCAPS_NEVER 能力だけしか持っていない場合、ドライバはアルファ テストをサポートしない。それ以外の場合、CONST_D3DPCMPCAPSFLAGS 列挙で定義されているフラグは、アルファ テストのためにサポートされている個々の比較を示す。
caps
CONST_D3DCAPSFLAGS 列挙によって定義されるドライバ固有の能力。
Caps2
ドライバ固有の能力。設定可能な値は、CONST_D3DCAPS2FLAGS 列挙で定義されている。
Caps3
この値は使用されていない。
CubeTextureFilterCaps
Direct3DCubeTexture オブジェクトのテクスチャ フィルタリング能力。ステージ単位のフィルタリング能力は、Direct3DDevice8 クラスでマルチテクスチャ ブレンディングを実行する際にテクスチャ ステージに対してサポートされるフィルタリング モードを示している。このメンバには、CONST_D3DPTFILTERCAPSFLAGS 列挙で定義されている一般およびステージ単位のテクスチャ フィルタリング フラグの、任意の組み合わせを設定できる。
CursorCaps
カーソルに対して利用できるハードウェア サポートを示すビット マスク。設定可能な値は、CONST_D3DCURSORCAPSFLAGS で定義されている。
DestBlendCaps
デスティネーション ブレンディング能力。このメンバには、CONST_D3DPBLENDCAPSFLAGS 列挙で定義されている 1 つ以上のフラグを設定できる。
DevCaps
デバイスの能力を示すフラグ。設定可能な値は、CONST_D3DDEVCAPSFLAGS 列挙で定義されている。
DeviceType
CONST_D3DDEVTYPE 列挙のメンバ。このデバイスに対してエミュレートされるすべての機能を示す。このパラメータの値では、このデバイスを作成した Direct3D8.CreateDevice の呼び出しに渡された値がそのまま示される。
ExtentsAdjust
アンチエイリアス カーネルが収まるように矩形の外辺を調節するためのピクセル数。
FVFCaps
柔軟な頂点フォーマットの能力。設定可能な値は、CONST_D3DFVFCAPSFLAGS 列挙で定義されている。
GuardBandBottom、GuardBandLeft、GuardBandRight、および GuardBandTop
ガードバンド クリッピング領域の画面空間座標。この矩形内にあり、かつビューポート矩形の外側にある座標は、自動的にクリッピングされる。
LineCaps
線描画プリミティブの能力を定義する。設定可能な値は、CONST_D3DLINECAPS 列挙で定義されている。
MaxActiveLights
同時にアクティブにすることができるライトの最大数。任意の物理デバイスの場合、この能力は、Direct3D8.CreateDevice に指定されたパラメータに応じて、Direct3D Device Object 間で異なることがある。
MaxAnisotropy
D3DTSS_MAXANISOTROPY テクスチャ ステージ ステートの最大有効値。
MaxPixelShaderValue
ピクセル シェーダの算術コンポーネントの最大値。この値は、ピクセル カラー ブレンディング処理でサポートされる値の内部範囲を示す。実装では、レポートされる範囲のデータが、変更 (制限) されずにピクセル処理に渡されるようにしなければならない。通常、このメンバの値は絶対値である。たとえば、1.0 は -1.0～1.0 の範囲を示し、8.0 は -8.0～8.0 の範囲を示す。この値が 0.0 の場合は、符号付きの範囲がサポートされていないことを示し、範囲は Microsoft DirectX® バージョン 6.0 および 7.0 と同様に 0.0～1.0 になる。
MaxPointSize
ポイント プリミティブの最大サイズ。1.0f に設定されている場合、デバイスはポイントのサイズの制御をサポートしていない。範囲は 1.0 以上である。
MaxPrimitiveCount
DrawPrimitive の各呼び出しの最大プリミティブ数。
MaxSimultaneousTextures
テクスチャ ブレンディング ステージに同時にバインドできるテクスチャの最大数。この値は、シングル パスで使用できるテクスチャの数を指定する。Microsoft® DirectX® 8.0 では、これは特定のハードウェアのピクセル シェーダによってサポートされるテクスチャ レジスタの数、および使用できるテクスチャ宣言命令の数を示す。
MaxStreams
Direct3DDevice8.SetStreamSourceに対する現在のデータ ストリームの最大数。有効な範囲は 1 から 16 である。この値が 0 の場合、ドライバは Microsoft DirectX® 8.0 ドライバ以外のものであることに注意すること。
MaxStreamStride
Direct3DDevice8.SetStreamSource の最大ストライド。
MaxTextureAspectRatio
ハードウェアによってサポートされる、テクスチャの最大アスペクト比。通常は 2 の累乗。
MaxTextureBlendStages
サポートされるテクスチャ ブレンディング ステージの最大数。この値は、使用可能なブレンダの数である。DirectX 8.0 のプログラム可能ピクセル パイプラインでは、これは、この特定の実装のピクセル シェーダによってサポートされている命令数に対応する。
MaxTextureHeight および MaxTextureWidth
このデバイスで最大のテクスチャの高さと幅。
MaxTextureRepeat
正規化した後のテクスチャ インデックスの整数ビットの全範囲。D3DPTEXTURECAPS_TEXREPEATNOTSCALEDBYSIZE ビットが設定されている場合、デバイスは、テクスチャ アドレッシング モードが適用されるまでテクスチャ サイズによるスケーリングを行わない。このビットが設定されていない場合、デバイスはテクスチャ サイズ (最大詳細レベル) によるテクスチャ インデックスのスケーリングを実行してから補間を行う。

D3DPTEXTURECAPS_TEXREPEATNOTSCALEDBYSIZE が設定されている場合、テクスチャをラップできる回数は MaxTextureRepeat である。D3DPTEXTURECAPS_TEXREPEATNOTSCALEDBYSIZE が設定されていない場合、テクスチャをラップできる回数はMaxTextureRepeat × テクスチャ サイズである。たとえば、デバイスが D3DPTEXTURECAPS_TEXREPEATNOTSCALEDBYSIZE を設定し、MaxTextureRepeat が 32k で、最大テクスチャ サイズが 4k であるとする。このデバイスは、27 の整数ビット (および 32 ビット符号付き整数の場合は 5 つの小数ビット) を使用するので、4k のテクスチャを 32k 回ラップするのに十分である (テクスチャ座標が、正と負のテクスチャ座標の範囲に等しく広がっていると仮定した場合)。一方、デバイスが D3DPTEXTURECAPS_TEXREPEATNOTSCALEDBYSIZE を設定できない場合は、MaxTextureRepeat を 2**27 に設定する。

MaxUserClipPlanes
サポートされるユーザー定義クリップ面の最大数。このメンバは 0 から D3DMAXUSERCLIPPLANES までの範囲になる。任意の物理デバイスの場合、この能力は、Direct3D8.CreateDevice に指定されたパラメータに応じて、Direct3D Device Object 間で異なることがある。
MaxVertexBlendMatrices
複数の行列による頂点ブレンディングを実行する際にデバイスが適用できる行列の最大数。任意の物理デバイスの場合、この能力は、Direct3D8.CreateDevice に指定されたパラメータに応じて、Direct3D Device Object 間で異なることがある。
MaxVertexBlendMatrixIndex
頂点ごとのインデックスを使ってインデックス付けできる最大の行列インデックスを示す値。行列の数は MaxVertexBlendMatrixIndex + 1 で、これは行列パレットのサイズである。ライティングにブレンディングする必要のある頂点データに法線が存在する場合、行列の数は、この能力フラグで示されている数の半分になる。MaxVertexBlendMatrixIndex が 0 に設定されている場合、ドライバはインデックス付き頂点ブレンディングをサポートしていない。この値が 0 でない場合は、インデックスの有効な範囲は 0 から MaxVertexBlendIndexedMatrices までである。

MaxVertexBlendMatrixIndex の値が 0 の場合は、ドライバがインデックス付き行列をサポートしていないことを示す。

ソフトウェア頂点処理が使われている場合は、法線ブレンディングがあってもなくても、256 個の行列をインデックス付き頂点ブレンディングに使用できる。

任意の物理デバイスの場合、この能力は、Direct3D8.CreateDevice に指定されたパラメータに応じて、Direct3D Device Object 間で異なることがある。

MaxVertexIndex
ハードウェア頂点処理に対してサポートされるインデックスの最大サイズ。D3DFMT_INDEX32 を指定して 32 ビット インデックス バッファを作成できる。ただし、この値が &HFFFF よりも大きくない場合は、インデックス バッファを使ってレンダリングできない。
MaxVertexW
デバイスがサポートする最大の W ベース深度値。
MaxVolumeExtent
最大ボリューム範囲。
MaxVertexShaderConst
頂点シェーダ定数レジスタの数。
PixelShaderVersion
ピクセル シェーダのバージョン。デバイスがサポートするピクセル シェーダのレベルを示す。Direct3DDevice8.CreatePixelShader の呼び出しは、このメンバの値以下のバージョン番号のピクセル シェーダを指定した場合にのみ成功する。
  • DirectX 8.0 機能は 01。

主なバージョン番号は、セカンド バイトにエンコードされる。下位バイトには、サブバージョンの番号が含まれる。

PresentationIntervals
利用可能なプレゼンテーション スワップ間隔を示す値のビット マスク。設定可能な値は、CONST_D3DPRESENT_INTERVAL_FLAGS 列挙で定義されている。
PrimitiveMiscCaps
このプリミティブの総体的な能力。設定可能な値は、CONST_D3DPMISCCAPSFLAGS 列挙で定義されている。
RasterCaps
ラスタ描画能力の情報。このメンバには、CONST_D3DPRASTERCAPSFLAGS 列挙で定義されている 1 つ以上のフラグを設定できる。
ShadeCaps
シェーディング処理能力。一般に、デバイスが何らかのコマンドをサポートしている場合、そのデバイスは D3DSHADE_FLAT モード (CONST_D3DSHADEMODE 列挙で指定される) をサポートしていると見なされる。このフラグは、ドライバがグーロー シェーディングもサポートできるかどうか、およびアルファ成分がサポートされているかどうかを示す。アルファ成分がサポートされていない場合、生成された色のアルファ値は暗黙で 255 になる。この数値が、アルファの最大値 (アルファ成分が最強) である。

三角形の色、スペキュラ ハイライト、フォグ、およびアルファの各補間要素にはそれぞれ能力フラグがあり、アプリケーションはそのフラグを使用して、デバイス ドライバがそれらをどのように実装しているかを知ることができる。

このメンバには、CONST_D3DPSHADECAPSFLAGS 列挙で定義されている 1 つ以上のフラグを設定できる。

SrcBlendCaps
ソース ブレンディング能力。このメンバには、CONST_D3DPBLENDCAPSFLAGS 列挙で定義されている 1 つ以上のフラグを設定できる。
StencilCaps
サポートされているステンシル バッファ処理を指定するフラグ。ステンシル処理は、3 種類のステンシル バッファ処理レンダリング ステート (D3DRS_STENCILFAIL、D3DRS_STENCILPASS、D3DRS_STENCILFAILZFAIL) のすべてに対して有効であると見なされる。設定可能な値は、CONST_D3DSTENCILCAPFLAGS 列挙で定義されている。

詳細については、「CONST_D3DSTENCILOP 列挙」を参照すること。

TextureAddressCaps
Direct3DTexture オブジェクトのテクスチャ アドレッシング能力。このメンバには、CONST_D3DPTADDRESSCAPSFLAGS 列挙で定義されている 1 つ以上のフラグを設定できる。
TextureCaps
その他のテクスチャ マッピング能力。このメンバには、CONST_D3DPTEXTURECAPSFLAGS 列挙で定義されている 1 つ以上のフラグを設定できる。
TextureFilterCaps
Direct3DTexture オブジェクトのテクスチャ フィルタリング能力。一般的なテクスチャ フィルタリング フラグは、どのテクスチャ フィルタリング モードをサポートするかを示し、D3DTSS_MAGFILTER、D3DTSS_MINFILTER、または D3DTSS_MIPFILTER のテクスチャ ステージ ステートに設定できる。ステージ単位のフィルタリング能力は、Direct3DDevice8 クラスでマルチテクスチャ ブレンディングを実行する際にテクスチャ ステージに対してサポートされるフィルタリング モードを示している。このメンバには、CONST_D3DPTFILTERCAPSFLAGS 列挙で定義されている一般およびステージ単位のテクスチャ フィルタリング フラグの、任意の組み合わせを設定できる。
TextureOpCaps
このデバイスがサポートするテクスチャ処理を示すフラグの組み合わせ。設定可能な値は、CONST_D3DTEXOPCAPSFLAGS 列挙で定義されている。

詳細については、「CONST_D3DTEXTUREOP 列挙」を参照すること。

VertexProcessingCaps
頂点の処理能力。設定可能な値は、CONST_D3DVTXPCAPSFLAGS 列挙で定義されている。任意の物理デバイスの場合、この能力は、Direct3D8.CreateDevice に指定されたパラメータに応じて、Direct3D Device Object 間で異なることがある。
VertexShaderVersion
頂点シェーダのバージョン。デバイスがサポートする頂点シェーダのレベルを示す。Direct3DDevice8.CreateVertexShader の呼び出しは、このメンバの値以下のバージョン番号の頂点シェーダを指定した場合にのみ成功する。CreateVertexShader に対するシェーダのレベルの指定は、頂点シェーダ トークン ストリームの第 1 トークンで行われる。
  • DirectX 7.0 の機能は 0。
  • DirectX 8.0 機能は 01。

主なバージョン番号は、セカンド バイトにエンコードされる。下位バイトには、サブバージョンの番号が含まれる。

VolumeTextureAddressCaps
Direct3DVolumeTexture オブジェクトのテクスチャ アドレッシング能力。このメンバには、CONST_D3DPTADDRESSCAPSFLAGS 列挙で定義されている 1 つ以上のフラグを設定できる。
VolumeTextureFilterCaps
Direct3DVolumeTexture オブジェクトのテクスチャ フィルタリング能力。ステージ単位のフィルタリング能力は、Direct3DDevice8 クラスでマルチテクスチャ ブレンディングを実行する際にテクスチャ ステージに対してサポートされるフィルタリング モードを示している。このメンバは、TextureFilterCaps 用に定義されたステージ単位のテクスチャ フィルタリング フラグを任意に組み合わせたものである。このメンバには、CONST_D3DPTFILTERCAPSFLAGS 列挙で定義されている一般およびステージ単位のテクスチャ フィルタリング フラグの、任意の組み合わせを設定できる。
ZCmpCaps
Z バッファ比較能力。このメンバには、AlphaCmpCaps メンバに対して定義されているものと同じ能力フラグを設定できる。このメンバに対するフラグは、CONST_D3DPCMPCAPSFLAGS 列挙で定義されている。

注意

MaxTextureBlendStages メンバと MaxSimultaneousTextures メンバは同じもののように見えるが、互いに異なる情報を含んでいる。MaxTextureBlendStages メンバは、現在のデバイスでサポートされるテクスチャ ブレンディング ステージの総数を示し、MaxSimultaneousTextures メンバは、Direct3DDevice8.SetTexture メソッドを使ってこれらのステージのうち何個のステージでテクスチャをバインドできるかを示す。

ドライバがこの型に値を設定する場合、能力の取得に使用するクラス (Direct3DDevice8 など) が実行バッファをサポートしていなくても、実行バッファ能力の値が設定される場合がある。

ミップマップ テクスチャに関連する次のフラグは、DirectX 8.0 ではサポートされていない。

  • D3DPTFILTERCAPS_NEAREST
  • D3DPTFILTERCAPS_LINEAR
  • D3DPTFILTERCAPS_MIPNEAREST
  • D3DPTFILTERCAPS_MIPLINEAR
  • D3DPTFILTERCAPS_LINEARMIPNEAREST
  • D3DPTFILTERCAPS_LINEARMIPLINEAR

参照

Direct3D8.GetDeviceCaps、Direct3DDevice8.GetDeviceCaps


D3DCLIPSTATUS8

現在のクリップ ステータスを記述する。

Type D3DCLIPSTATUS8
    ClipUnion As Long
    ClipIntersection As Long
End Type

メンバ

ClipUnion
現在のクリップ ステータスを示すクリップ結合フラグ。このメンバには、CONST_D3DCLIPFLAGS 列挙で定義されている 1 つ以上のフラグを設定できる。
ClipIntersection
現在のクリップ ステータスを示すクリップ交点フラグ。このメンバの値は、ClipUnion と同じフラグである。

参照

Direct3DDevice8.GetClipStatus、Direct3DDevice8.SetClipStatus


D3DCOLORVALUE

カラー値を記述する。

Type D3DCOLORVALUE
    a As Single
    b As Single
    g As Single
    r As Single
End Type

メンバ

a、b、g、および r
色の赤 (red)、緑 (green)、青 (blue)、およびアルファ (alpha) の各成分を指定する値。一般に、これらの値は 0 から 1 までの範囲で、0 は黒である。

注意

特殊なエフェクトを出すために、この型のメンバを 0 から 1 の範囲外の値に設定することができる。1 より大きい値を指定すると、シーンを洗い流すような強い光が生成される。マイナスの値を指定すると、暗い光が生成されて、実際にはシーンから光が除かれてしまう。

参照

ライティングとマテリアルのカラー値


D3DDEVICE_CREATION_PARAMETERS

デバイスの作成パラメータを記述する。

Type D3DDEVICE_CREATION_PARAMETERS
    AdapterOrdinal As Long
    BehaviorFlags As Long
    DeviceType As CONST_D3DDEVTYPE
    hFocusWindow As Long
End Type

メンバ

AdapterOrdinal
ディスプレイ アダプタを示す序数。D3DADAPTER_DEFAULT は常にプライマリ ディスプレイ アダプタである。

任意の Direct3D8 メソッドの Adapter パラメータには、この番号を使用する。Direct3D8 オブジェクトが異なると使用する番号が異なる場合があることに注意する。たとえば、ユーザーがマルチ モニタ システムにモニタを追加したりシステムからモニタを外したために、またはラップトップをホット スワップしたために、アダプタがシステムに加えられたり除かれたりする場合がある。したがって、この番号が有効であることがわかっている Direct3D8 においてのみ使用しなければならない。有効な Direct3D8 インスタンスは、この Direct3DDevice8 オブジェクトを作成した Direct3D8 と、この Direct3DDevice8 オブジェクトを通して呼び出した Direct3DDevice8.GetDirect3D から返る Direct3D8 の 2 つだけである。

BehaviorFlags
Microsoft® Direct3D® デバイスの全体的な動作を制御するフラグの組み合わせ。設定可能な値は、CONST_D3DCREATEFLAGS 列挙で定義されている。

このパラメータの値では、このデバイスを作成した Direct3D8.CreateDevice の呼び出しに渡された値がそのまま示される。

DeviceType
CONST_D3DDEVTYPE 列挙のメンバ。このデバイスに対してエミュレートされるすべての機能を示す。このパラメータの値では、このデバイスを作成した CreateDevice の呼び出しに渡された値がそのまま示される。
hFocusWindow
この Direct3D デバイスでフォーカスを設定するウィンドウ ハンドル。このパラメータの値では、このデバイスを作成した CreateDevice の呼び出しに渡された値がそのまま示される。

参照

Direct3DDevice8.GetCreationParameters、Direct3D8.CreateDevice


D3DDISPLAYMODE

ディスプレイ モードを記述する。

Type D3DDISPLAYMODE
    Format As CONST_D3DFORMAT
    Height As Long
    RefreshRate As Long
    Width As Long
End Type

メンバ

Format
ディスプレイ モードのサーフェス フォーマットを示す CONST_D3DFORMAT 列挙のメンバ。
Height
ピクセル単位で表したスクリーンの高さ。
RefreshRate
リフレッシュ レート。0 は、アダプタのデフォルトを示す。
Width
ピクセル単位で表したスクリーンの幅。

参照

Direct3D8.EnumAdapterModes、Direct3D8.GetAdapterDisplayMode、Direct3DDevice8.GetDisplayMode


D3DGAMMARAMP

赤、緑、青の各ランプのデータを格納する。

Type D3DGAMMARAMP
    blue(0 To 255) As Integer
    green(0 To 255) As Integer
    red(0 To 255) As Integer
End Type

メンバ

blue、green、および red
赤、緑、および青のガンマ ランプを記述する 256 個の Integer 要素の配列。

参照

Direct3DDevice8.GetGammaRamp、Direct3DDevice8.SetGammaRamp


D3DINDEXBUFFER_DESC

インデックス バッファを記述する。

Type D3DINDEXBUFFER_DESC
    Format As CONST_D3DFORMAT
    Pool As CONST_D3DPOOL
    Size As Long
    Type As CONST_D3DRESOURCETYPE
    Usage As Long
End Type

メンバ

Format
インデックス バッファ データのサーフェス フォーマットを示す CONST_D3DFORMAT 列挙のメンバ。
Pool
このインデックス バッファに割り当てられているメモリのクラスを示す CONST_D3DPOOL 列挙のメンバ。
Size
バイト単位で示したインデックス バッファのサイズ。
Type
このリソースがインデックス バッファであることを示す CONST_D3DRESOURCETYPE 列挙のメンバ。
Usage
このリソースの使用方法を指定する CONST_D3DUSAGEFLAGS 列挙で定義される次の 1 つ以上のフラグの組み合わせ。
D3DUSAGE_DONOTCLIP
インデックス バッファの内容が決してクリッピングを要求しないことを示す。
D3DUSAGE_HOSURFACES
高次プリミティブの描画にインデックス バッファを使用するとき設定する。
D3DUSAGE_RTPATCHES
高次プリミティブの描画に頂点バッファを使用するとき設定する。
D3DUSAGE_NPATCHES
N パッチの描画にインデックス バッファを使用するとき設定する。
D3DUSAGE_POINTS
ポイント スプライトまたはインデックス付きポイント リストの描画に、インデックス バッファを使用するとき設定する。
D3DUSAGE_SOFTWAREPROCESSING
バッファがソフトウェア処理で使用されることを示す。
D3DUSAGE_WRITEONLY
インデックス バッファへの書き込み操作しか実行できないことをシステムに通知する。このフラグを使用することにより、ドライバは最適なメモリ領域を選択して効率的に書き込み操作やレンダリングを実行する。この能力を使用して作成されたインデックス バッファからの読み込みを試みると、パフォーマンスが低下する場合がある。

参照

Direct3DIndexBuffer8.GetDesc


D3DLIGHT8

一連のライト プロパティを定義する。

Type D3DLIGHT8
    ambient As D3DCOLORVALUE
    diffuse As D3DCOLORVALUE
    specular As D3DCOLORVALUE
    type As CONST_D3DLIGHTTYPE
    Attenuation0 As Single
    Attenuation1 As Single
    Attenuation2 As Single
    Direction As D3DVECTOR
    Falloff As Single
    Phi As Single
    position As D3DVECTOR
    Range As Single
    Theta As Single
End Type

メンバ

ambient
ライトが放射するアンビエント色。このメンバは、D3DCOLORVALUE 型である。
diffuse
ライトが放射するディフューズ色。このメンバは D3DCOLORVALUE 型である。
specular
ライトが放射するスペキュラ色。このメンバは D3DCOLORVALUE 型である。
type
光源の種類。この値は、CONST_D3DLIGHTTYPE 列挙のメンバの 1 つである。
Attenuation0、Attenuation1、および Attenuation2
光の輝度が距離によってどのように変化するかを指定する値。ディレクショナル ライトの場合、減衰値は無視される。これらのメンバは減衰定数を表す。減衰については、「距離の増加によるライトの減衰」を参照すること。これらのメンバの有効な値の範囲は、0.0 から無限大である。ディレクショナル ライト以外の場合、3 つの減衰値すべてを同時に 0.0 に設定してはならない。
Direction
ワールド空間で光が指す方向。D3DVECTOR 型で指定される。このメンバは、ディレクショナル ライトおよびスポット ライトの場合にのみ意味を持つ。このベクトルは正規化する必要はないが、ゼロでない長さを持たなければならない。
Falloff
スポット ライトの内部コーン (Thetaで指定される角度) と外部コーン (Phi で指定される角度) の外側エッジとの間で輝度がフォールオフする。

ライティングに対するフォールオフの影響は微妙である。さらに、フォールオフ カーブを描くと多少の性能上のロスを被る。これらの理由により、開発者の多くはこの値を 1.0 にセットする。

Phi
スポット ライトの外円錐の外側のエッジを定義する角度をラジアン単位で表す。この円錐の外側にある点はスポット ライトでライティングされない。この値は 0 から pi の範囲になければならない。
position
ワールド空間内での光源の位置座標。D3DVECTOR 型で指定される。このメンバは、ディレクショナル ライトにおいては意味がなく、無視される。
Range
光源の有効距離。このメンバの最大許容値は FLT_MAX の平方根である。このメンバはディレクショナル ライトには影響しない。
Theta
スポット ライトの内円錐をラジアン単位で表す。つまり、スポット ライトが明瞭に照らす円錐である。この値は、0 から Phi による指定値の範囲になければならない。

参照

Direct3DDevice8.GetLight、Direct3DDevice8.SetLight


D3DLINEPATTERN

線パターンを記述する。

Type D3DLINEPATTERN
    LinePattern As Integer
    RepeatFactor As Integer
End Type

メンバ

LinePattern
線パターンを指定するビット。たとえば、次の値は点線を生成する: 1100110011001100
RepeatFactor
LinePattern メンバで指定する連続した 1 および 0 を繰り返す回数。これにより、アプリケーションでは線パターンを拡大できる。

注意

これらの値は、CONST_D3DRENDERSTATETYPE 列挙の D3DRS_LINEPATTERN レンダリング ステートによって使用される。

線パターンは線の描き方を指定する。線パターンは描き出す始点の位置にかかわらず常に同じである (これは点描とは異なる。点描はオブジェクトのレンダリング方法、つまり透過性の表現方法に影響する)。

線パターンでは、線に沿った 16 個のピクセルのオン/オフ パターンを指定する。RepeatFactor メンバでは、LinePattern の各エントリに対して繰り返すピクセルの数を指定する。


D3DLOCKED_BOX

ロックされたボックス (ボリューム) を記述する。

Type D3DLOCKED_BOX
    pBits As Long
    RowPitch As Long
    SlicePitch As Long
End Type

メンバ

pBits
ロック済みビット。D3DBOX が LockRect の呼び出しに提供されている場合、pBits はボリュームの先頭から適切にオフセットされる。
RowPitch
バイト単位で表した行ピッチ。
SlicePitch
バイト単位で表したスライス ピッチ。

注意

幅 × 高さの 2D サーフェスのスライスを積み重ねて、幅 × 高さ × 深さのボリュームを作成することで、ボリュームは視覚化することができる。詳細については、「ボリューム テクスチャ リソース」を参照すること。

参照

Direct3DVolume8.LockBox、Direct3DVolumeTexture8.LockBox


D3DLOCKED_RECT

ロックされた矩形領域を記述する。

Type D3DLOCKED_RECT
    pBits As Long
    Pitch As Long
End Type

メンバ

pBits
ロック済みビット。RECT が LockRect の呼び出しに提供されている場合、pBits はサーフェスの先頭から適切にオフセットされる。
Pitch
バイト単位で表したサーフェス ピッチ。

参照

Direct3DCubeTexture8.LockRect、Direct3DSurface8.LockRect、Direct3DTexture8.LockRect


D3DLVERTEX

未トランスフォーム、ライティング済みの頂点 (色情報付きモデル座標) を定義する。

Type D3DLVERTEX
    color As Long
    specular As Long
    tu As Single
    tv As Single
    x As Single
    y As Single
    z As Single
End Type

メンバ

color および specular
頂点の色およびスペキュラ成分を記述する値。
tu および tv
頂点のテクスチャ座標を記述する値。
x、y、および z
頂点の同次座標を指定する値。

注意

頂点トランスフォームが Microsoft® Direct3D® によって処理される場合、アプリケーションではこの型を使用しなければならない。この型には、ソフトウェア ライティングによって設定されるデータおよび色だけが含まれる。

D3DRS_SPECULARENABLE が TRUE の場合は、テクスチャ カスケード後、アルファ ブレンディング前に、ベース カラーにスペキュラ成分が追加される。ただし、D3DTA_SPECULAR フラグを設定することにより、テクスチャ カラーに適用するスペキュラ成分を割り当てることができる。詳細については、「テクスチャ引数フラグ」を参照すること。


D3DLVERTEX2

未トランスフォーム、ライティング済みの頂点 (色情報付きモデル座標) を、2 組のテクスチャ座標で定義する。

Type D3DLVERTEX2
    color As Long
    specular As Long
    tu1 As Single
    tu2 As Single
    tv1 As Single
    tv2 As Single
    x As Single
    y As Single
    z As Single
End Type

メンバ

color および specular
頂点の色およびスペキュラ成分を記述する値。
tu1 および tv1
頂点のテクスチャ座標の最初のセットを記述する値。
tu2 および tv2
頂点のテクスチャ座標の 2 つ目のセットを記述する値。
x、y、および z
頂点の同次座標を指定する値。

注意

マルチテクスチャ処理の多くでは 2 組のテクスチャ座標が必要になる。D3DLVERTEX2 はそのような処理での便宜を考慮して提供されている。

頂点トランスフォームが Microsoft® Direct3D® によって処理される場合、アプリケーションではこの型を使用しなければならない。この型には、ソフトウェア ライティングによって設定されるデータおよび色だけが含まれる。

D3DRS_SPECULARENABLE が TRUE の場合は、テクスチャ カスケード後、アルファ ブレンディング前に、ベース カラーにスペキュラ成分が追加される。ただし、D3DTA_SPECULAR フラグを設定することにより、テクスチャ カラーに適用するスペキュラ成分を割り当てることができる。詳細については、「テクスチャ引数フラグ」を参照すること。


D3DMATERIAL8

マテリアルのプロパティを指定する。

Type D3DMATERIAL8
    ambient As D3DCOLORVALUE
    diffuse As D3DCOLORVALUE
    emissive As D3DCOLORVALUE
    power As Single
    specular As D3DCOLORVALUE
End Type

メンバ

ambient、diffuse、emissive、および specular
それぞれ、マテリアルのアンビエント色、ディフューズ色、エミッション色、スペキュラ色を指定する値。これらの値は、D3DCOLORVALUE 型である。
power
スペキュラ ハイライトの鮮明度を指定する値。マテリアルのスペキュラ ハイライトをオフにするには、このメンバを 0 に設定する。スペキュラ色成分を 0 に設定するだけでは不十分である。

参照

Direct3DDevice8.GetMaterial、Direct3DDevice8.SetMaterial


D3DMATRIX

行列を記述する。

Type D3DMATRIX
    m11 As Single
    m12 As Single
    m13 As Single
    m14 As Single
    m21 As Single
    m22 As Single
    m23 As Single
    m24 As Single
    m31 As Single
    m32 As Single
    m33 As Single
    m34 As Single
    m41 As Single
    m42 As Single
    m43 As Single
    m44 As Single
End Type

注意

Microsoft® Direct3D® では、射影行列の m34 要素は負にできない。ここでアプリケーションで負の値を使用する必要がある場合は、代わりに射影行列全体を -1 でスケーリングする。

参照

Direct3DDevice8.GetTransform、Direct3DDevice8.MultiplyTransform、Direct3DDevice8.SetTransform


D3DPLANE

平面を記述する。

Type D3DPLANE
    a As Single
    b As Single
    c As Single
    d As Single
End Type

メンバ

a、b、c、および d
それぞれ、一般平面式で表すクリップ面の a、b、c、および d の各係数。「注意」を参照すること。

注意

D3DPLANE 型のメンバでは、一般平面式の形式が使われる。これらのメンバは、ax + by + cz + dw = 0 のような一般平面式の係数として使われる。


D3DPRESENT_PARAMETERS

プレゼンテーション パラメータを記述する。

Type D3DPRESENT_PARAMETERS
    AutoDepthStencilFormat As CONST_D3DFORMAT
    BackBufferCount As Long
    BackBufferFormat As CONST_D3DFORMAT
    BackBufferHeight As Long
    BackBufferWidth As Long
    EnableAutoDepthStencil As Long
    Flags As Long
    FullScreen_PresentationInterval As Long
    FullScreen_RefreshRateInHz As Long
    hDeviceWindow As Long
    MultiSampleType As CONST_D3DMULTISAMPLE_TYPE
    SwapEffect As CONST_D3DSWAPEFFECT
    Windowed As Long
End Type

メンバ

AutoDepthStencilFormat
CONST_D3DFORMAT 列挙のメンバ。デバイスが作成する自動深度ステンシル サーフェスのフォーマットである。EnableAutoDepthStencil が 0 以外の値 (TRUE) でない場合、このメンバは無視される。
BackBufferCount
この値には、0、1、2、または 3 を設定できる。0 は 1 として処理されることに注意する。バック バッファの数を作成できない場合、Microsoft® Direct3D はメソッドの呼び出しに失敗し、作成できたバック バッファ数をこの値に設定する。したがって、アプリケーションは同じ D3DPRESENT_PARAMETERS 型を指定してメソッドを 2 回呼び出すことができ、2 回目には呼び出しが成功するものと予想される。

バック バッファの数の最小値は 1 と想定されている。バック バッファを 1 つも作成できない場合、メソッドの呼び出しは失敗する。BackBufferCount の値は、使用可能なスワップ エフェクトのセットに影響を与える。特に、D3DSWAPEFFECT_COPY スワップ エフェクトでは、存在するバック バッファが厳密に 1 つでなければならない。

BackBufferFormat
CONST_D3DFORMAT 列挙のメンバ。この値は、Direct3D8.CheckDeviceType で検証されたレンダリング ターゲットのフォーマットのいずれかでなければならない。

Windowed を TRUE に設定する場合、BackBufferFormat の設定は、現在のディスプレイ モードのフォーマットと一致している必要がある。現在のフォーマットを取得するには、Direct3DDevice8.GetDisplayMode を使用する。

BackBufferHeight および BackBufferWidth
新しいスワップ チェーンのバック バッファの高さと幅 (ピクセル単位)。Windowed が 0 (FALSE) でプレゼンテーションがフルスクリーンの場合、これらの値は、Direct3D8.EnumAdapterModes によって列挙されたディスプレイ モードのいずれかの高さおよび幅と一致していなければならない。Windowed が TRUE で、これらの値のいずれかが 0 の場合は、hDeviceWindow (または hDeviceWindow が Nothing の場合はフォーカス ウィンドウ) のクライアント領域の対応するディメンジョンが使用される。
EnableAutoDepthStencil
この値が TRUE の場合、Direct3D® はアプリケーションに対する深度バッファを管理する。デバイスは、作成されると、深度ステンシル バッファを作成する。深度ステンシル バッファは、デバイスのレンダリング ターゲットとして自動的に設定される。デバイスがリセットされると、深度ステンシル バッファは自動的に破棄されて、新しいサイズで再度作成される。

EnableAutoDepthStencil が TRUE の場合、AutoDepthStencilFormat は有効な深度ステンシル フォーマットでなければならない。

Flags
現在、この値は使用されておらず、0 に設定しなければならない。
FullScreen_PresentationInterval
利用可能なプレゼンテーション スワップ間隔を示す値のビット マスク。ウィンドウ モードの場合、この値は 0 でなければならない。それ以外の場合、この値は D3DCAPS8 の PresentationIntervals メンバで列挙される値のいずれかでなければならない。設定可能な値は、CONST_D3DPRESENT_INTERVAL_FLAGS 列挙で定義されている。
FullScreen_RefreshRateInHz
ディスプレイ アダプタによるスクリーンのリフレッシュ レート。ウィンドウ モードの場合、この値は 0 でなければならない。それ以外の場合は、Direct3D8.EnumAdapterModes が返すリフレッシュ レートのいずれか、または CONST_D3DPRESENT_RATE_FLAGS 列挙で定義されているリフレッシュ レートのいずれかでなければならない。
hDeviceWindow
フルスクリーン モードの場合、これはカバー ウィンドウである。ウィンドウ モードの場合、これは Direct3DDevice8.Present に対するデフォルトのターゲット ウィンドウである。この値が Nothing の場合は、フォーカス ウィンドウが使用される。マルチモニタ システムなど、複数のフルスクリーン デバイスを使用するアプリケーションの場合は、正確に 1 つのデバイスがデバイス ウィンドウとしてフォーカス ウィンドウを使用しなければならない。その他のすべてのウィンドウは、一意のデバイス ウィンドウを持つ。それ以外の場合は、動作は定義されておらず、アプリケーションは期待どおりに動作しない。

Direct3D はユーザーによるウィンドウ サイズの変更を反映しようとしないことに注意すること。このウィンドウがリセットされても、バック バッファが暗黙的にリセットされることはない。ただし、Present メソッドは、ウィンドウ位置の変化を自動的に追跡する。

MultiSampleType
CONST_D3DMULTISAMPLE_TYPE 列挙のメンバ。SwapEffect に D3DSWAPEFFECT_DISCARD が設定されていない場合、この値は D3DMULTISAMPLE_NONE でなければならない。マルチサンプリングは、スワップ エフェクトが D3DSWAPEFFECT_DISCARD の場合にのみサポートされる。
SwapEffect
CONST_D3DSWAPEFFECT 列挙のメンバ。Direct3D は、バッファ スワップ動作に関して指定されているセマンティクスを保証する。したがって、Windowed が TRUE で D3DSWAPEFFECT_FLIP の場合、Direct3D は 1 つ余分にバック バッファを作成し、プレゼンテーション時にフロント バッファになるものをすべてコピーする。

D3DSWAPEFFECT_COPY および D3DSWAPEFFECT_COPY_VSYNC の場合は、BackBufferCount に 1 が設定されていなければならない。

デバッグ ランタイムにおいては、提示した後のバッファにノイズを格納することで、D3DSWAPEFFECT_DISCARD を強制する。

Windowed
アプリケーションがウィンドウ モードで動作する場合は TRUE、フルスクリーン モードで動作する場合は FALSE である。

参照

Direct3D8.CreateDevice、Direct3DDevice8.CreateAdditionalSwapChain、Direct3DDevice8.Present、Direct3DDevice8.Reset


D3DQUATERNION

クオータニオンを記述する。

Type D3DQUATERNION
    w As Single
    x As Single
    y As Single
    z As Single
End Type

メンバ

w、x、y、および z
それぞれ、クオータニオンの w、x、y、および z の各要素。

注意

クオータニオンは、ベクトルを定義する [x, y, z] の値に第 4 の要素を追加し、結果として任意の 4D ベクトルが生成される。ただし、軸角度回転に対して正規化されたクオータニオンの各要素がどのように関係するかは、次に示すとおりである。ここで、q は正規化されたクオータニオン (x, y, z, w) を表し、axis は正規化されていて、theta は軸を中心とする目的の CCW 回転である。

q.x = Sin(theta / 2) * axis.x
q.y = Sin(theta / 2) * axis.y
q.z = Sin(theta / 2) * axis.z
q.w = Cos(theta / 2)


D3DRANGE

範囲を定義する。

Type D3DRANGE
    cbOffset As Long
    size As Long
End Type

メンバ

cbOffset
バイト単位で表したオフセット。
size
バイト単位で表したサイズ。


D3DRASTER_STATUS

ラスタ ステータスを記述する。

Type D3DRASTER_STATUS
    InVBLANK As Long
    ScanLine As Long
End Type

メンバ

InVBLANK
ラスタが垂直帰線消去間隔にある場合は TRUE である。ラスタが垂直帰線消去間隔にない場合は FALSE である。
ScanLine
InVBLANK が FALSE の場合、この値は、ラスタによって描画される現在の走査線にほぼ対応する整数値である。走査線には、Microsoft® Direct3D® のサーフェス座標と同じ方法で番号が付けられている。つまり、0 はプライマリ サーフェスの上端であり、ディスプレイ下端の値 (サーフェスの高さ -1) に達するまで増加する。

InVBLANK が TRUE の場合、この値は 0 に設定されて無視できる。


D3DRECT

矩形を定義する。

Type D3DRECT
    x1 As Long
    x2 As Long
    y1 As Long
    y2 As Long
End Type

メンバ

x1 および y1
矩形の左上隅の座標。
x2 および y2
矩形の右下隅の座標。

参照

Direct3DDevice8.Clear


D3DRECTPATCH_INFO

矩形の高次パッチを記述する。

Type D3DRECTPATCH_INFO
    Basis As CONST_D3DBASISTYPE
    Height As Long
    Order As CONST_D3DORDERTYPE
    StartVertexOffsetHeight As Long
    StartVertexOffsetWidth As Long
    StrideBytes As Long
    Width As Long
End Type

メンバ

Basis
矩形の高次パッチの基本タイプを定義する CONST_D3DBASISTYPE 型のメンバ。
Height
頂点の数で表した、各頂点の高さ。
Order
高次パッチのオーダー タイプを定義する CONST_D3DORDERTYPE 型のメンバ。
StartVertexOffsetHeight
頂点の数で表した、開始頂点オフセットの高さ。
StartVertexOffsetWidth
頂点の数で表した、開始頂点オフセットの幅。
StrideBytes
頂点の数で表した、セグメント間のストライド。
Width
頂点の数で表した、各頂点の幅。

注意

個々の矩形パッチのストリーム (非モザイク) をレンダリングするには、ジオメトリを細く長い (1 × N) 矩形パッチとして解釈しなければならない。このようなストリップ (立方体ベジェ) の D3DRECTPATCH_INFO 構造体は、次のように設定される。

Dim i As Integer
Dim RectInfo As D3DRECTPATCH_INFO

With D3DRECTPATCH_INFO
    .Width = 4
    .Height = 4
    .Stride = 4
    .Basis = D3DBASIS_BEZIER
    .Order = D3DORDER_CUBIC
    .StartVertexOffsetWidth = 0
    .StartVertexOffsetHeight = 4 * i  ' 変数 i はレンダリングするパッチのインデックスである。
End With

参照

Direct3DDevice8.DrawRectPatch


D3DSURFACE_DESC

サーフェスを記述する。

Type D3DSURFACE_DESC
    format As CONST_D3DFORMAT
    Height As Long
    MultiSampleType As CONST_D3DMULTISAMPLE_TYPE
    Pool As CONST_D3DPOOL
    size As Long
    type As CONST_D3DRESOURCETYPE
    Usage As Long
    Width As Long
End Type

メンバ

format
サーフェス フォーマットを示す CONST_D3DFORMAT 列挙のメンバ。
Height
ピクセルの単位で表したサーフェスの高さ。
MultiSampleType
サーフェスがサポートするフルシーン マルチサンプリングのレベルを示す CONST_D3DMULTISAMPLE_TYPE 列挙のメンバ。
Pool
このサーフェスに割り当てられているメモリのクラスを示す CONST_D3DPOOL 列挙のメンバ。
size
バイト単位で表されたサーフェスのサイズ。
type
サーフェスとしてのこのリソースを示す CONST_D3DRESOURCETYPE 列挙型のメンバ。
Usage
このリソースの使用方法を指定する CONST_D3DUSAGEFLAGS 列挙で定義される次の 1 つ以上のフラグの組み合わせ。
D3DUSAGE_DEPTHSTENCIL
サーフェスが深度ステンシル サーフェスとして使用されることを示す。
D3DUSAGE_RENDERTARGET
サーフェスがレンダリング ターゲットとして使用されることを示す。
Width
ピクセルの単位で表したサーフェスの幅。

参照

Direct3DCubeTexture8.GetLevelDesc、Direct3DSurface8.GetDesc、Direct3DTexture8.GetLevelDesc


D3DTLVERTEX

トランスフォーム済みライティング済みの頂点 (色情報付きスクリーン座標) を定義する。

Type D3DTLVERTEX
    color As Long
    rhw As Single
    specular As Long
    sx As Single
    sy As Single
    sz As Single
    tu As Single
    tv As Single
End Type

メンバ

color および specular
頂点の色およびスペキュラ成分を記述する値。
rhw
同次座標 (x,y,z,w) の同次 w の逆数。この値は、多くの場合、原点からオブジェクトまでの z 軸に沿った距離で 1 を除算した値と一致する。
sx、sy、および sz
頂点をスクリーン座標で示す値。表示される z 値の範囲内に頂点を置く場合、dvSZ のとり得る最大値は 1.0 までである。
tu および tv
頂点のテクスチャ座標を記述する値。

注意

Microsoft® Direct3D® は、現在のビューポート パラメータ (D3DVIEWPORT8 型の x、y、Width、および Height メンバ) を使用して D3DTLVERTEX 頂点をクリッピングする。システムは z 座標を常に [0, 1] にクリッピングする。

D3DRS_SPECULARENABLE が TRUE の場合は、テクスチャ カスケード後、アルファ ブレンディング前に、ベース カラーにスペキュラ成分が追加される。ただし、D3DTA_SPECULAR フラグを設定することにより、テクスチャ カラー適用するスペキュラ成分を割り当てることができる。詳細については、「テクスチャ引数フラグ」を参照すること。

参照

D3DTLVERTEX2、D3DVERTEX、D3DVERTEX2


D3DTLVERTEX2

トランスフォーム済みライティング済みの頂点 (色情報付きスクリーン座標) を、2 組のテクスチャ座標で定義する。

Type D3DTLVERTEX2
    color As Long
    rhw As Single
    specular As Long
    sx As Single
    sy As Single
    sz As Single
    tu1 As Single
    tu2 As Single
    tv1 As Single
    tv2 As Single
End Type

メンバ

color および specular
頂点の色およびスペキュラ成分を記述する値。
rhw
同次座標 (x,y,z,w) の同次 w の逆数。この値は、多くの場合、原点からオブジェクトまでの z 軸に沿った距離で 1 を除算した値と一致する。
sx、sy、および sz
頂点をスクリーン座標で示す値。表示される z 値の範囲内に頂点を置く場合、dvSZ のとり得る最大値は 1.0 までである。
tu1 および tv1
頂点のテクスチャ座標の最初のセットを記述する値。
tu2 および tv2
頂点のテクスチャ座標の 2 つ目のセットを記述する値。

注意

マルチテクスチャ処理の多くでは 2 組のテクスチャ座標が必要になる。D3DTLVERTEX2 はそのような処理での便宜を考慮して提供されている。

Microsoft® Direct3D® は、現在のビューポート パラメータ (D3DVIEWPORT8 型の x、y、Width、および Height メンバ) を使用して D3DTLVERTEX 頂点をクリッピングする。システムは z 座標を常に [0, 1] にクリッピングする。

D3DRS_SPECULARENABLE が TRUE の場合は、テクスチャ カスケード後、アルファ ブレンディング前に、ベース カラーにスペキュラ成分が追加される。ただし、D3DTA_SPECULAR フラグを設定することにより、テクスチャ カラーに適用するスペキュラ成分を割り当てることができる。詳細については、「テクスチャ引数フラグ」を参照すること。

参照

D3DVERTEX、D3DVERTEX2、D3DTLVERTEX


D3DTRIPATCH_INFO

三角形の高次パッチを記述する。

Type D3DTRIPATCH_INFO
    Basis As CONST_D3DBASISTYPE
    Order As CONST_D3DORDERTYPE
    StartVertexOffsetHeight As Long
    StartVertexOffsetWidth As Long
End Type

メンバ

Basis
三角形の高次パッチの基本タイプを定義する CONST_D3DBASISTYPE 型のメンバ。
Order
三角形のの高次パッチのオーダー タイプを定義する CONST_D3DORDERTYPE 型のメンバ。
StartVertexOffsetHeight
頂点の数で表した、開始頂点オフセットの高さ。
StartVertexOffsetWidth
頂点の数で表した、開始頂点オフセットの幅。

参照

Direct3DDevice8.DrawTriPatch


D3DVECTOR

3D 空間のベクトルを記述する。

Type D3DVECTOR
    x As Single
    y As Single
    z As Single
End Type

メンバ

x、y、および z
ベクトルを指定する値。

参照

D3DVECTOR2、D3DVECTOR4


D3DVECTOR2

2D 空間のベクトルを記述する。

Type D3DVECTOR2
    x As Single
    y As Single
End Type

メンバ

x および y
それぞれ、ベクトルの x 要素および y 要素。

参照

D3DVECTOR、D3DVECTOR4


D3DVECTOR4

4D 空間のベクトルを記述する。

Type D3DVECTOR4
    w As Single
    x As Single
    y As Single
    z As Single
End Type

メンバ

w、x、y、および z
それぞれ、ベクトルの w、x、y、および z の各成分。

参照

D3DVECTOR、D3DVECTOR2


D3DVERTEX

未トランスフォーム未ライティングの頂点 (正規方向ベクトルでのモデル座標) を定義する。

Type D3DVERTEX
    nx As Single
    ny As Single
    nz As Single
    tu As Single
    tv As Single
    x As Single
    y As Single
    z As Single
End Type

メンバ

nx、ny、および nz
頂点の正規座標を指定する値。
tu および tv
頂点のテクスチャ座標を記述する値。
x、y、および z
頂点の同次座標を指定する値。

参照

D3DTLVERTEX


D3DVERTEX2

未トランスフォーム未ライティングの頂点 (正規方向ベクトルでのモデル座標) を、2 組のテクスチャ座標で定義する。

Type D3DVERTEX2
    nx As Single
    ny As Single
    nz As Single
    tu1 As Single
    tu2 As Single
    tv1 As Single
    tv2 As Single
    x As Single
    y As Single
    z As Single
End Type

メンバ

nx、ny、および nz
頂点の正規座標を指定する値。
tu1 および tv1
頂点のテクスチャ座標の最初のセットを記述する値。
tu2 および tv2
頂点のテクスチャ座標の 2 つ目のセットを記述する値。
x、y、および z
頂点の同次座標を指定する値。

注意

マルチテクスチャ処理の多くでは 2 組のテクスチャ座標が必要になる。D3DVERTEX2 はそのような処理での便宜を考慮して提供されている。

参照

D3DVERTEX、D3DTLVERTEX、D3DTLVERTEX2


D3DVERTEXBUFFER_DESC

頂点バッファを記述する。

Type D3DVERTEXBUFFER_DESC
    format As CONST_D3DFORMAT
    FVF As Long
    Pool As CONST_D3DPOOL
    size As Long
    type As CONST_D3DRESOURCETYPE
    Usage As Long
End Type

メンバ

format
頂点バッファ データのサーフェス フォーマットを示す CONST_D3DFORMAT 列挙のメンバ。
FVF
このバッファ内の頂点の頂点フォーマットを示す柔軟な頂点フォーマット フラグの組み合わせ。
Pool
この頂点バッファに割り当てられているメモリのクラスを示す CONST_D3DPOOL 列挙のメンバ。
size
バイト単位で示した頂点バッファのサイズ。
type
このリソースが頂点バッファであることを示す CONST_D3DRESOURCETYPE 列挙のメンバ。
Usage
このリソースの使用方法を指定する CONST_D3DUSAGEFLAGS 列挙で定義される次の 1 つ以上のフラグの組み合わせ。
D3DUSAGE_DONOTCLIP
頂点バッファの内容が決してクリッピングを要求しないことを示す。
D3DUSAGE_HOSURFACES
高次プリミティブの描画に頂点バッファを使用するとき設定する。
D3DUSAGE_RTPATCHES
高次プリミティブの描画に頂点バッファを使用するとき設定する。
D3DUSAGE_NPATCHES
N パッチの描画に頂点バッファを使用するとき設定する。
D3DUSAGE_POINTS
ポイント スプライトまたはインデックス付きポイント リストの描画に、頂点バッファを使用するとき設定する。
D3DUSAGE_SOFTWAREPROCESSING
ソフトウェア頂点処理で使用する頂点バッファであることを示す。
D3DUSAGE_WRITEONLY
頂点バッファへの書き込み操作しか実行できないことをシステムに知らせる。このフラグを使用することにより、ドライバは最適なメモリ領域を選択して効率的に書き込み操作やレンダリングを実行する。この能力を利用して作成した頂点バッファから読み出しを行おうとすると、パフォーマンスが低下することがある。

参照

Direct3DVertexBuffer8.GetDesc


D3DVIEWPORT8

3D ボリュームが射影されるレンダリング ターゲット サーフェスのウィンドウの大きさを定義する。

Type D3DVIEWPORT8
    MaxZ As Single
    MinZ As Single
    Height As Long
    Width As Long
    x As Long
    y As Long
End Type

メンバ

MaxZ および MinZ
シーンをレンダリングする深度値の範囲を示す値。クリップ ボリュームの最小値と最大値。ほとんどのアプリケーションでは、これらの値をそれぞれ 0.0 および 1.0 に設定する。射影行列の適用後にクリッピングが行われる。
Height および Width
レンダリング ターゲット サーフェス上のビューポートのディメンジョン (ピクセル単位)。サーフェスのサブセットに限定してレンダリングするのでなければ、これらのメンバにはレンダリング ターゲット サーフェスのディメンジョンを設定する。
x および y
レンダリング ターゲット サーフェス上のビューポートの左上隅を表すピクセル座標。サーフェスのサブセットにレンダリングするのでなければ、これらのメンバは 0 に設定してよい。

注意

x、y、Width、および Height メンバは、レンダリング ターゲット サーフェス上のビューポートの位置と大きさを記述する。通常、アプリケーションはターゲット サーフェス全体にレンダリングするので、640 × 480 のサーフェスにレンダリングするときは、これらのメンバはそれぞれ 0、0、640、480 になる。一般に、MinZ および MaxZ は 0.0 および 1.0 に設定されるが、ほかの値を設定して特殊効果を出すこともできる。たとえば、両方の値を 0.0 に設定すると、シーンのフォアグラウンドにオブジェクトがレンダリングされる。また、両方の値を 1.0 に設定すると、オブジェクトがバックグラウンドにレンダリングされる。

デバイスのビューポート パラメータを変更すると (Direct3DDevice8.SetViewport メソッドの呼び出しにより)、ドライバは新しいトランスフォーム行列を作成する。

参照

Direct3DDevice8.GetViewport、Direct3DDevice8.SetViewport


D3DVOLUME_DESC

ボリュームを記述する。

Type D3DVOLUME_DESC
    Depth As Long
    format As CONST_D3DFORMAT
    Height As Long
    Pool As CONST_D3DPOOL
    size As Long
    type As CONST_D3DRESOURCETYPE
    Usage As Long
    Width As Long
End Type

メンバ

Depth
ピクセル単位で表されたボリュームの深度。
format
ボリュームのサーフェス フォーマットを示す CONST_D3DFORMAT 列挙のメンバ。
Height
ピクセル単位で表されたボリュームの高さ。
Pool
このボリュームに割り当てられているメモリのクラスを示す CONST_D3DPOOL 列挙のメンバ。
size
バイト単位で表されたボリュームのサイズ。
type
このリソースがボリュームであることを示す CONST_D3DRESOURCETYPE 列挙のメンバ。
Usage
現在は使用されていない。常に 0 が返される。
Width
ピクセル単位で表されたボリュームの幅。

参照

Direct3DVolume8.GetDesc、Direct3DVolumeTexture8.GetLevelDesc


列挙

ここでは、Microsoft® Direct3D® で使用される以下の列挙について説明する。

  • CONST_D3DBACKBUFFERTYPE
  • CONST_D3DBASISTYPE
  • CONST_D3DBLEND
  • CONST_D3DBLENDOP
  • CONST_D3DCAPS2FLAGS
  • CONST_D3DCAPSFLAGS
  • CONST_D3DCLEARFLAGS
  • CONST_D3DCLIPFLAGS
  • CONST_D3DCLIPPLANEFLAGS
  • CONST_D3DCMPFUNC
  • CONST_D3DCOLORWRITEENABLEFLAGS
  • CONST_D3DCONST
  • CONST_D3DCREATEFLAGS
  • CONST_D3DCUBEMAP_FACES
  • CONST_D3DCULL
  • CONST_D3DCURSORCAPSFLAGS
  • CONST_D3DDEBUGMONITORTOKENS
  • CONST_D3DDEVCAPSFLAGS
  • CONST_D3DDEVTYPE
  • CONST_D3DERR
  • CONST_D3DFILLMODE
  • CONST_D3DFOGMODE
  • CONST_D3DFORMAT
  • CONST_D3DFVFCAPSFLAGS
  • CONST_D3DFVFFLAGS
  • CONST_D3DFVFTEXTUREFORMATS
  • CONST_D3DLIGHTTYPE
  • CONST_D3DLINECAPS
  • CONST_D3DLOCKFLAGS
  • CONST_D3DMATERIALCOLORSOURCE
  • CONST_D3DMULTISAMPLE_TYPE
  • CONST_D3DORDERTYPE
  • CONST_D3DPATCHEDGESTYLE
  • CONST_D3DPBLENDCAPSFLAGS
  • CONST_D3DPCMPCAPSFLAGS
  • CONST_D3DPMISCCAPSFLAGS
  • CONST_D3DPOOL
  • CONST_D3DPRASTERCAPSFLAGS
  • CONST_D3DPRESENT_INTERVAL_FLAGS
  • CONST_D3DPRESENT_RATE_FLAGS
  • CONST_D3DPRIMITIVETYPE
  • CONST_D3DPSHADECAPSFLAGS
  • CONST_D3DPTADDRESSCAPSFLAGS
  • CONST_D3DPTEXTURECAPSFLAGS
  • CONST_D3DPTFILTERCAPSFLAGS
  • CONST_D3DRENDERSTATETYPE
  • CONST_D3DRESOURCETYPE
  • CONST_D3DSCPFLAGS
  • CONST_D3DSGRFLAGS
  • CONST_D3DSHADEMODE
  • CONST_D3DSPDFLAGS
  • CONST_D3DSTATEBLOCKTYPE
  • CONST_D3DSTENCILCAPFLAGS
  • CONST_D3DSTENCILOP
  • CONST_D3DSWAPEFFECT
  • CONST_D3DTAFLAGS
  • CONST_D3DTEXOPCAPSFLAGS
  • CONST_D3DTEXTUREADDRESS
  • CONST_D3DTEXTUREFILTERTYPE
  • CONST_D3DTEXTUREOP
  • CONST_D3DTEXTURESTAGESTATETYPE
  • CONST_D3DTEXTURETRANSFORMFLAGS
  • CONST_D3DTRANSFORMSTATETYPE
  • CONST_D3DTSS_TCI_FLAGS
  • CONST_D3DUSAGEFLAGS
  • CONST_D3DVERTEXBLENDFLAGS
  • CONST_D3DVTXPCAPSFLAGS
  • CONST_D3DWRAPBIAS
  • CONST_D3DWRAPFLAGS
  • CONST_D3DZBUFFERTYPE


CONST_D3DBACKBUFFERTYPE

バック バッファのタイプを記述する定数を定義する。

Enum CONST_D3DBACKBUFFERTYPE
    D3DBACKBUFFER_TYPE_MONO  = 0
    D3DBACKBUFFER_TYPE_LEFT  = 1
    D3DBACKBUFFER_TYPE_RIGHT = 2
End Enum

定数

D3DBACKBUFFER_TYPE_MONO
非ステレオ スワップ チェーンを指定する。
D3DBACKBUFFER_TYPE_LEFT
スワップ チェーンのステレオ ペアの左側を指定する。
D3DBACKBUFFER_TYPE_RIGHT
スワップ チェーンのステレオ ペアの右側を指定する。

注意

DirectX 8.0 ではステレオ ビューはサポートされていないので、この列挙の D3DBACKBUFFER_TYPE_LEFT および D3DBACKBUFFER_TYPE_RIGHT の値は Direct3D では使用されない。

参照

Direct3DDevice8.GetBackBuffer、Direct3DSwapChain8.GetBackBuffer


CONST_D3DBLEND

サポートされているブレンディング モードを定義する。

Enum CONST_D3DBLEND
    D3DBLEND_ZERO            =  1
    D3DBLEND_ONE             =  2
    D3DBLEND_SRCCOLOR        =  3
    D3DBLEND_INVSRCCOLOR     =  4
    D3DBLEND_SRCALPHA        =  5
    D3DBLEND_INVSRCALPHA     =  6
    D3DBLEND_DESTALPHA       =  7
    D3DBLEND_INVDESTALPHA    =  8
    D3DBLEND_DESTCOLOR       =  9
    D3DBLEND_INVDESTCOLOR    = 10
    D3DBLEND_SRCALPHASAT     = 11
    D3DBLEND_BOTHSRCALPHA    = 12
    D3DBLEND_BOTHINVSRCALPHA = 13
End Enum

定数

D3DBLEND_ZERO
ブレンディング係数は、(0, 0, 0, 0)。
D3DBLEND_ONE
ブレンディング係数は、(1, 1, 1, 1)。
D3DBLEND_SRCCOLOR
ブレンディング係数は、(Rs, Gs, Bs, As)。
D3DBLEND_INVSRCCOLOR
ブレンディング係数は、(1-Rs, 1-Gs, 1-Bs, 1-As)。
D3DBLEND_SRCALPHA
ブレンディング係数は、(As, As, As, As)。
D3DBLEND_INVSRCALPHA
ブレンディング係数は、(1-As, 1-As, 1-As, 1-As)。
D3DBLEND_DESTALPHA
ブレンディング係数は、(Ad, Ad, Ad, Ad)。
D3DBLEND_INVDESTALPHA
ブレンディング係数は、(1-Ad, 1-Ad, 1-Ad, 1-Ad)。
D3DBLEND_DESTCOLOR
ブレンディング係数は、(Rd, Gd, Bd, Ad)。
D3DBLEND_INVDESTCOLOR
ブレンディング係数は、(1-Rd, 1-Gd, 1-Bd, 1-Ad)。
D3DBLEND_SRCALPHASAT
ブレンディング係数は (f, f, f, 1)、f = min(As, 1-Ad)。
D3DBLEND_BOTHSRCALPHA
サポートされていない。
D3DBLEND_BOTHINVSRCALPHA
ソース ブレンディング係数は、(1-As, 1-As, 1-As, 1-As)。デスティネーション ブレンディング係数は、(As, As, As, As)。デスティネーションのブレンディングの選択は無効になる。

注意

前述のメンバの説明では、転送元および転送先の RGBA 値は添字 s および d によって示される。

これらのフラグは、CONST_D3DRENDERSTATETYPE 列挙の D3DRS_SRCBLEND および D3DRS_DESTBLEND の各レンダリング ステートの値を設定するために使われる。

参照

CONST_D3DRENDERSTATETYPE


CONST_D3DBLENDOP

サポートされているブレンディング処理を定義する。

Enum CONST_D3DBLENDOP
    D3DBLENDOP_ADD         = 1
    D3DBLENDOP_SUBTRACT    = 2
    D3DBLENDOP_REVSUBTRACT = 3
    D3DBLENDOP_MIN         = 4
    D3DBLENDOP_MAX         = 5
End Enum

定数

D3DBLENDOP_ADD
転送元に転送先が加算される。

結果 = 転送元 + 転送先

D3DBLENDOP_SUBTRACT
転送元から転送先が減算される。

結果 = 転送元 - 転送先

D3DBLENDOP_REVSUBTRACT
転送先から転送元が減算される。

結果 = 転送先 - 転送元

D3DBLENDOP_MIN
転送元および転送先の最小値を返す。

結果 = MIN(転送元, 転送先)

D3DBLENDOP_MAX
転送元および転送先の最大値を返す。

結果 = MAX(転送元, 転送先)

注意

この列挙型は、D3DRS_BLENDOP レンダリング ステートで使用される値を定義する。

参照

D3DCAPS8、CONST_D3DRENDERSTATETYPE


CONST_D3DCAPS2FLAGS

ドライバ固有の能力を定義する。

Enum CONST_D3DCAPS2FLAGS
    D3DCAPS2_NO2DDURING3DSCENE =        2
    D3DCAPS2_FULLSCREENGAMMA   =   131072 (&H20000)
    D3DCAPS2_CANRENDERWINDOWED =   524288 (&H80000)
    D3DCAPS2_CANCALIBRATEGAMMA =  1048576 (&H100000)
    D3DCAPS2_RESERVED          = 33554432 (&H2000000)
End Enum

定数

D3DCAPS2_NO2DDURING3DSCENE
ドライバによって D3DCAPS2_NO2DDURING3DSCENE 能力が設定されている場合、Direct3DDevice8.BeginScene と Direct3DDevice8.EndScene の呼び出しの間では 2D 処理を実行できない。

通常、この能力は、シーンをパーティション化し、シーン内の各パーティションをレンダリングするハードウェアによって設定される。パーティション化はドライバによって実行され、ハードウェアはイメージ パーティションのサイズに対応する小さな色および深度バッファを格納する。このタイプのレンダリング ハードウェアでは、通常、イメージの各部分がレンダリングされると、カラー バッファ内のデータはビデオ メモリに書き込まれ、深度バッファの内容は破棄される。また、3D レンダリングは EndScene が検出されるまで開始されないことに注意する。次に、シーンが領域ごとに処理される。この場合、処理の順序は保証されない。たとえば、処理される最初の領域 (通常ウィンドウの左上隅) が、フレームの最後の三角形を含んでいる場合がある。これと従来のグラフィックス システムを比較すると、一般的なシステムでは、各コマンドは送信された順に逐次処理される。2D 処理は、処理における特定の時点で行われることが想定されている。D3DCAPS2_NO2DDURING3DSCENE を設定するシステムでは、処理の順序は保証されないので、3D レンダリング中に検出された 2D 処理はディスプレイ アダプタによって破棄される場合がある。

一般的には、BeginScene と EndScene のペアの外側で 2D 処理を実行することを推奨する。2D 処理が BeginScene と EndScene のペアの間で実行される場合は、D3DCAPS2_NO2DDURING3DSCENE 能力をチェックする必要がある。この能力が設定されている場合、アプリケーションでは、BeginScene と EndScene の間にある 2D 処理は破棄されると考える必要がある。D3DCAPS2_NO2DDURING3DSCENE を設定するシステム用のアプリケーション作成の詳細については、「注意」を参照すること。

D3DCAPS2_FULLSCREENGAMMA
ドライバは、フルスクリーン モードでのダイナミック ガンマ ランプ調整をサポートしている。
D3DCAPS2_CANRENDERWINDOWED
ドライバは、ウィンドウ モードのレンダリングができる。
D3DCAPS2_CANCALIBRATEGAMMA
システムには、自動的にガンマ ランプを調節できるインストールされた口径測定器があるので、その結果は口径測定器のある全システム上で示される。新しいガンマ レベルを設定するときに口径測定器を起動するには、Direct3DDevice8.SetGammaRamp メソッドを呼び出す際に D3DSGR_CALIBRATE フラグを使用する。ガンマ ランプのキャリブレーションでは、いくつかの処理にオーバーヘッドが起こるので、頻繁に使用できない。
D3DCAPS2_RESERVED
このフラグは、将来使用するために予約されている。使用不可。

注意

これらのフラグは、組み合わせて、D3DCAPS8 の Caps2 メンバで使用できる。

D3DCAPS2_NO2DDURING3DSCENE 能力フラグを設定するシステムの場合は、テクスチャを使用し、シーン中に変更するとパフォーマンスの問題が発生することがある。これはすべてのハードウェアに該当するが、D3DCAPS2_NO2DDURING3DSCENE 能力を公開するハードウェアでより深刻である。ハードウェアに D3DCAPS2_NO2DDURING3DSCENE が存在する場合、アプリケーション ベースのテクスチャ管理では、現在の BeginScene と EndScene ブロック内で使用されているテクスチャが、本当に必要でない限り、除外されないようにしなければならない。

シーン内で大量のテクスチャが使用されている場合、つまりシーン内で使用されているテクスチャを変更し、使用可能なテクスチャ メモリが不足している場合、その結果は不定である。このようなシステムでは、Z バッファの内容は EndScene で無効になる。アプリケーションは、このタイプのハードウェア上では、BeginScene と EndScene の間で、バック バッファへの、またはバック バッファからの Direct3DDevice8.CopyRects を呼び出すべきではない。さらに、D3DPRASTERCAPS_ZBUFFERLESSHSR 能力フラグが設定されている場合、アプリケーションは Z バッファにアクセスすべきではない。最後に、アプリケーションは BeginScene と EndScene のペアの間で、バック バッファまたは Z バッファをロックすべきではない。

参照

D3DCAPS8


CONST_D3DCAPSFLAGS

ドライバ固有の能力を定義する。

Enum CONST_D3DCAPSFLAGS
    D3DCAPS_READ_SCANLINE = 131072 (&H20000)
End Enum

定数

D3DCAPS_READ_SCANLINE
ディスプレイ ハードウェアが、現在の走査線を返せることを示す。

注意

このフラグは、D3DCAPS8 の Caps メンバで使用できる。

参照

D3DCAPS8


CONST_D3DCLEARFLAGS

クリアするサーフェスを示す定数を定義する。

Enum CONST_D3DCLEARFLAGS
    D3DCLEAR_TARGET  = 1
    D3DCLEAR_ZBUFFER = 2
    D3DCLEAR_STENCIL = 4
End Enum

定数

D3DCLEAR_TARGET
レンダリング ターゲットをクリアする。
D3DCLEAR_ZBUFFER
深度バッファをクリアする。
D3DCLEAR_STENCIL
ステンシル バッファをクリアする。

参照

Direct3DDevice8.Clear


CONST_D3DCLIPFLAGS

クリップ ステータスを定義する。

Enum CONST_D3DCLIPFLAGS
    D3DCS_LEFT   =    1
    D3DCS_RIGHT  =    2
    D3DCS_TOP    =    4
    D3DCS_BOTTOM =    8
    D3DCS_FRONT  =   16 (&H10)
    D3DCS_BACK   =   32 (&H20)
    D3DCS_PLANE0 =   64 (&H40)
    D3DCS_PLANE1 =  128 (&H80)
    D3DCS_PLANE2 =  256 (&H100)
    D3DCS_PLANE3 =  512 (&H200)
    D3DCS_PLANE4 = 1024 (&H400)
    D3DCS_PLANE5 = 2048 (&H800)
    D3DCS_ALL    = 4095 (&HFFF)
End Enum

定数

D3DCS_LEFT
すべての頂点を視錐台の左側面でクリッピングする。
D3DCS_RIGHT
すべての頂点を視錐台の右側面でクリッピングする。
D3DCS_TOP
すべての頂点を視錐台の上面でクリッピングする。
D3DCS_BOTTOM
すべての頂点を視錐台の底面でクリッピングする。
D3DCS_FRONT
すべての頂点を視錐台の前面でクリッピングする。
D3DCS_BACK
すべての頂点を視錐台の背面でクリッピングする。
D3DCS_PLANE0 ～ D3DCS_PLANE5
アプリケーション定義のクリップ面。
D3DCS_ALL
すべてのクリップ フラグの組み合わせ。

注意

これらのフラグは、組み合わせて、D3DCLIPSTATUS8 の ClipUnion メンバおよび ClipIntersection メンバで使用できる。

参照

D3DCLIPSTATUS8


CONST_D3DCLIPPLANEFLAGS

ユーザー定義クリップ面を有効にする定数を定義する。

Enum CONST_D3DCLIPPLANEFLAGS
    D3DCLIPPLANE0 =  1
    D3DCLIPPLANE1 =  2
    D3DCLIPPLANE2 =  4
    D3DCLIPPLANE3 =  8
    D3DCLIPPLANE4 = 16 (&H10)
    D3DCLIPPLANE5 = 32 (&H20)
End Enum

定数

D3DCLIPPLANE0 ～ D3DCLIPPLANE5
対応するインデックスにあるクリップ面を有効にする (0 ～ 5)。この値を組み合わせて、複数のクリップ面を同時に有効にすることができる。

注意

これらのフラグは、CONST_D3DRENDERSTATETYPE 列挙の D3DRS_CLIPPLANEENABLE レンダリング ステートの値を設定するために使われる。

参照

CONST_D3DRENDERSTATETYPE


CONST_D3DCMPFUNC

サポートされる比較関数を定義する。

Enum CONST_D3DCMPFUNC
    D3DCMP_NEVER        = 1
    D3DCMP_LESS         = 2
    D3DCMP_EQUAL        = 3
    D3DCMP_LESSEQUAL    = 4
    D3DCMP_GREATER      = 5
    D3DCMP_NOTEQUAL     = 6
    D3DCMP_GREATEREQUAL = 7
    D3DCMP_ALWAYS       = 8
End Enum

定数

D3DCMP_NEVER
常にテストは失敗する。
D3DCMP_LESS
新しいピクセル値が、現在のピクセル値より小さいときに応じる。
D3DCMP_EQUAL
新しいピクセル値が、現在のピクセル値と等しいときに応じる。
D3DCMP_LESSEQUAL
新しいピクセル値が、現在のピクセル値以下のときに応じる。
D3DCMP_GREATER
新しいピクセル値が、現在のピクセル値より大きいときに応じる。
D3DCMP_NOTEQUAL
新しいピクセル値が、現在のピクセル値と等しくないときに応じる。
D3DCMP_GREATEREQUAL
新しいピクセル値が、現在のピクセル値以上のときに応じる。
D3DCMP_ALWAYS
常にテストはパスする。

注意

これらのフラグは、CONST_D3DRENDERSTATETYPE 列挙の D3DRS_ZFUNC、D3DRS_ALPHAFUNC、および D3DRS_STENCILFUNC の各レンダリング ステートの値を設定するために使われる。

参照

CONST_D3DRENDERSTATETYPE


CONST_D3DCOLORWRITEENABLEFLAGS

3D レンダリング中に更新するカラー チャネルを定義する。

Enum CONST_D3DCOLORWRITEENABLEFLAGS
    D3DCOLORWRITEENABLED_RED   = 1
    D3DCOLORWRITEENABLED_GREEN = 2
    D3DCOLORWRITEENABLED_BLUE  = 4
    D3DCOLORWRITEENABLED_ALPHA = 8
End Enum

定数

D3DCOLORWRITEENABLED_RED
赤のカラー チャネルを指定する。
D3DCOLORWRITEENABLED_GREEN
緑のカラー チャネルを指定する。
D3DCOLORWRITEENABLED_BLUE
青のカラー チャネルを指定する。
D3DCOLORWRITEENABLED_ALPHA
アルファのカラー チャネルを指定する。

注意

これらのフラグは、CONST_D3DRENDERSTATETYPE 列挙の D3DRS_COLORWRITEENABLE レンダリング ステートの値を設定するために使われる。

参照

CONST_D3DRENDERSTATETYPE


CONST_D3DCONST

Microsoft® Direct3D® で使われるさまざまな定数を定義する。

Enum CONST_D3DCONST
    D3D_OK                             =        0
    D3DADAPTER_DEFAULT                 =        0
    D3DCURSOR_IMMEDIATE_UPDATE         =        1
    D3DENUM_HOST_ADAPTER               =        1
    D3DPRESENTFLAG_LOCKABLE_BACKBUFFER =        1
    D3DPV_DONOTCOPYDATA                =        1
    D3DENUM_NO_WHQL_LEVEL              =        2
    D3DPRESENT_BACK_BUFFERS_MAX        =        3
    VALID_D3DENUM_FLAGS                =        3
    D3DMAXNUMPRIMITIVES                =    65535 (&HFFFF)
    D3DMAXNUMVERTICES                  =    65535 (&HFFFF)
    D3DCURRENT_DISPLAY_MODE            = 15728639 (&HEFFFFF)
End Enum

定数

D3D_OK
Err.Number を設定するのではなく、エラー コードを返すメソッドとの互換性を表す成功コード。
D3DADAPTER_DEFAULT
プライマリ ディスプレイ アダプタ。
D3DCURSOR_IMMEDIATE_UPDATE
リフレッシュ レートでカーソルを更新する。
D3DENUM_HOST_ADAPTER
このリリースではドキュメント化されていない。
D3DPRESENTFLAG_LOCKABLE_BACKBUFFER
アプリケーションがバック バッファを直接ロックする必要がある場合は、このフラグを設定する。アプリケーションが Direct3D8.CreateDevice および Direct3DDevice8.Reset で D3DPRESENTFLAG_LOCKABLE_BACKBUFFER を指定しない限り、バック バッファはロックできないことに注意すること。ロック可能なバック バッファによって、一部のグラフィックス ハードウェア構成ではパフォーマンスのコストが向上する。

ロック可能なバック バッファでロック処理を実行すると (または読み書きに Direct3DDevice8.CopyRects を使用すると)、多くのカードでパフォーマンスが低下する。この場合は、テクスチャ化した三角形を使ってデータをバック バッファに移動することを検討する必要がある。

D3DPV_DONOTCOPYDATA
頂点処理に無関係な頂点データはコピー先バッファにコピーしない。
D3DENUM_NO_WHQL_LEVEL
D3DADAPTER_IDENTIFIER8 型の WHQLLevel メンバをゼロに設定する。これにより、WHQL 認証期日に情報が返されなくなる。このフラグを設定すると、WHQL の認証期日を確認する際に発生する 1、2 秒の遅れを防ぐことができる。
D3DPRESENT_BACK_BUFFERS_MAX
Microsoft® DirectX® 8.0 でサポートされているバック バッファの最大数。
VALID_D3DENUM_FLAGS
このリリースではドキュメント化されていない。
D3DMAXNUMPRIMITIVES
任意の Direct3D 描画メソッドに渡すことのできるプリミティブの最大数。
D3DMAXNUMVERTICES
任意の Direct3D 描画関数または頂点バッファ作成メソッドに渡すことのできる頂点の最大数。
D3DCURRENT_DISPLAY_MODE
アダプタの現在のデスクトップ ディスプレイ モードを示す。

参照

Direct3DDevice8.SetCursorPosition


CONST_D3DCREATEFLAGS

Microsoft® Direct3D® デバイス作成フラグを定義する。

Enum CONST_D3DCREATEFLAGS
    D3DCREATE_FPU_PRESERVE              = 2
    D3DCREATE_MULTITHREADED             = 4
    D3DCREATE_PUREDEVICE                = 16 (&H10)
    D3DCREATE_SOFTWARE_VERTEXPROCESSING = 32 (&H20)
    D3DCREATE_HARDWARE_VERTEXPROCESSING = 64 (&H40)
    D3DCREATE_MIXED_VERTEXPROCESSING    = 128 (&H80)
End Enum

定数

D3DCREATE_FPU_PRESERVE
アプリケーションで倍精度 FPU または FPU 例外を有効にする必要があることを示す。Direct3D は、呼び出されるたびに FPU の状態を設定する。このフラグを設定すると、Direct3D のパフォーマンスが低下する。
D3DCREATE_MULTITHREADED
アプリケーションが Direct3D にマルチスレッドでの安全性を要求することを示す。Direct3D はグローバル クリティカル セクションをいっそう頻繁に取得するようになり、パフォーマンスが低下する可能性がある。
D3DCREATE_PUREDEVICE
ハードウェアによるラスタ化、トランスフォーム、ライティング、およびシェーディングを指定する。このフラグは、必ず D3DCREATE_HARDWARE_VERTEXPROCESSING と共に指定する必要がある。
D3DCREATE_SOFTWARE_VERTEXPROCESSING
ソフトウェアによる頂点処理を指定する。「注意」を参照すること。
D3DCREATE_HARDWARE_VERTEXPROCESSING
ハードウェアによる頂点処理を指定する。「注意」を参照すること。
D3DCREATE_MIXED_VERTEXPROCESSING
混合 (ソフトウェアとハードウェアの両方) 頂点処理を指定する。「注意」を参照すること。

注意

D3DCREATE_HARDWARE_VERTEXPROCESSING、D3DCREATE_MIXED_VERTEXPROCESSING、および D3DCREATE_SOFTWARE_VERTEXPROCESSING は相互に排他的なフラグであり、Direct3D8.CreateDevice を呼び出すときは、これらの頂点処理フラグの少なくとも 1 つを必ず指定しなければならない。

参照

Direct3D8.CreateDevice


CONST_D3DCUBEMAP_FACES

キューブマップの面を定義する。

Enum CONST_D3DCUBEMAP_FACES
    D3DCUBEMAP_FACE_POSITIVE_X = 0
    D3DCUBEMAP_FACE_NEGATIVE_X = 1
    D3DCUBEMAP_FACE_POSITIVE_Y = 2
    D3DCUBEMAP_FACE_NEGATIVE_Y = 3
    D3DCUBEMAP_FACE_POSITIVE_Z = 4
    D3DCUBEMAP_FACE_NEGATIVE_Z = 5
End Enum

定数

D3DCUBEMAP_FACE_POSITIVE_X
キューブマップの正方向の x 面。
D3DCUBEMAP_FACE_NEGATIVE_X
キューブマップの負方向の x 面。
D3DCUBEMAP_FACE_POSITIVE_Y
キューブマップの正方向の y 面。
D3DCUBEMAP_FACE_NEGATIVE_Y
キューブマップの負方向の y 面。
D3DCUBEMAP_FACE_POSITIVE_Z
キューブマップの正方向の z 面。
D3DCUBEMAP_FACE_NEGATIVE_Z
キューブマップの負方向の z 面。

参照

Direct3DCubeTexture8.AddDirtyRect、Direct3DCubeTexture8.GetCubeMapSurface、Direct3DCubeTexture8.LockRect、Direct3DCubeTexture8.UnlockRect


CONST_D3DCULL

サポートするカリング モードを定義する。

Enum CONST_D3DCULL
    D3DCULL_NONE = 1
    D3DCULL_CW   = 2
    D3DCULL_CCW  = 3
End Enum

定数

D3DCULL_NONE
背面のカリングはしない。
D3DCULL_CW
背面を右回りにカリングする。
D3DCULL_CCW
背面を左回りにカリングする。

注意

この列挙型の値は、CONST_D3DRENDERSTATETYPE 列挙の D3DRS_CULLMODE レンダリング ステートの値を設定するために使われる。

カリング モードは、ジオメトリをレンダリングするときの背面のカリング方法を定義する。

参照

D3DCAPS8、CONST_D3DRENDERSTATETYPE


CONST_D3DCURSORCAPSFLAGS

カーソルの能力を定義する。

Enum CONST_D3DCURSORCAPSFLAGS
    D3DCURSORCAPS_COLOR   = 1
    D3DCURSORCAPS_LOWRES  = 2
End Enum

定数

D3DCURSORCAPS_COLOR
ハードウェアは、黒と白の 2 色カーソルをサポートしている。
D3DCURSORCAPS_LOWRES
ハードウェアは、フルカラー カーソルをサポートしている。

注意

Microsoft® Direct3D® for Microsoft DirectX® 8.0 では、アルファ ブレンディング カーソルの能力は定義されていない。

参照

D3DCAPS8


CONST_D3DDEBUGMONITORTOKENS

デバッグ モニタ トークンを定義する。

Enum CONST_D3DDEBUGMONITORTOKENS
    D3DDMT_ENABLE  = 0
    D3DDMT_DISABLE = 1
End Enum

定数

D3DDMT_ENABLE
デバッグ モニタを有効にする。
D3DDMT_DISABLE
デバッグ モニタを無効にする。

注意

この列挙型の値は、D3DRS_DEBUGMONITORTOKEN レンダリング ステートで使用され、デバッグ ビルドにのみ関連する。

参照

CONST_D3DRENDERSTATETYPE


CONST_D3DDEVCAPSFLAGS

デバイスの能力を定義する。

Enum CONST_D3DDEVCAPSFLAGS
    D3DDEVCAPS_EXECUTESYSTEMMEMORY     =       16 (&H10)
    D3DDEVCAPS_EXECUTEVIDEOMEMORY      =       32 (&H20)
    D3DDEVCAPS_TLVERTEXSYSTEMMEMORY    =       64 (&H40)
    D3DDEVCAPS_TLVERTEXVIDEOMEMORY     =      128 (&H80)
    D3DDEVCAPS_TEXTURESYSTEMMEMORY     =      256 (&H100)
    D3DDEVCAPS_TEXTUREVIDEOMEMORY      =      512 (&H200)
    D3DDEVCAPS_DRAWPRIMITIVES2         =     8192 (&H2000)
    D3DDEVCAPS_DRAWPRIMTLVERTEX        =     1024 (&H400)
    D3DDEVCAPS_CANRENDERAFTERFLIP      =     2048 (&H800)
    D3DDEVCAPS_TEXTURENONLOCALVIDMEM   =     4096 (&H1000)
    D3DDEVCAPS_SEPARATETEXTUREMEMORIES =    16384 (&H4000)
    D3DDEVCAPS_DRAWPRIMITIVES2EX       =    32768 (&H8000)
    D3DDEVCAPS_HWTRANSFORMANDLIGHT     =    65536 (&H10000)
    D3DDEVCAPS_CANBLTSYSTONONLOCAL     =   131072 (&H20000)
    D3DDEVCAPS_HWRASTERIZATION         =   524288 (&H80000)
    D3DDEVCAPS_PUREDEVICE              =  1048576 (&H100000)
    D3DDEVCAPS_QUINTICRTPATCHES        =  2097152 (&H200000)
    D3DDEVCAPS_RTPATCHES               =  4194304 (&H400000)
    D3DDEVCAPS_RTPATCHHANDLEZERO       =  8388608 (&H800000)
    D3DDEVCAPS_NPATCHES                = 16777216 (&H1000000)
End Enum

定数

D3DDEVCAPS_EXECUTESYSTEMMEMORY
デバイスは、システム メモリにある実行バッファを使用できる。
D3DDEVCAPS_EXECUTEVIDEOMEMORY
デバイスは、ビデオ メモリにある実行バッファを使用できる。
D3DDEVCAPS_TLVERTEXSYSTEMMEMORY
デバイスは、トランスフォーム済みライティング済みの頂点用に、システム メモリのバッファを使用できる。
D3DDEVCAPS_TLVERTEXVIDEOMEMORY
デバイスは、トランスフォーム済みライティング済みの頂点用に、ビデオ メモリのバッファを使用できる。
D3DDEVCAPS_TEXTURESYSTEMMEMORY
デバイスは、システム メモリからテクスチャを取得できる。
D3DDEVCAPS_TEXTUREVIDEOMEMORY
デバイスは、デバイス メモリからテクスチャを取得できる。
D3DDEVCAPS_DRAWPRIMITIVES2
このリリースではドキュメント化されていない。
D3DDEVCAPS_DRAWPRIMTLVERTEX
デバイスは、DrawPrimitive 対応のハードウェア アブストラクション レイヤ (HAL) をエクスポートする。
D3DDEVCAPS_CANRENDERAFTERFLIP
デバイスは、ページ フリップの後で、レンダリング コマンドをキューに入れることができる。このフラグはアプリケーションの動作を変えるものではない。デバイスが比較的高速であることを示しているだけである。
D3DDEVCAPS_TEXTURENONLOCALVIDMEM
デバイスは、非ローカル ビデオ メモリからテクスチャを取得できる。
D3DDEVCAPS_SEPARATETEXTUREMEMORIES
デバイスは、独立したメモリ プールからテクスチャ処理を行っている。
D3DDEVCAPS_DRAWPRIMITIVES2EX
このリリースではドキュメント化されていない。
D3DDEVCAPS_HWTRANSFORMANDLIGHT
デバイスは、ハードウェアでトランスフォーム & ライティングをサポートできる。
D3DDEVCAPS_CANBLTSYSTONONLOCAL
デバイスは、システム メモリ テクスチャから非ローカル ビデオ メモリ テクスチャへのブリットをサポートする。
D3DDEVCAPS_HWRASTERIZATION
デバイスには、シーンのラスタ化用のハードウェア アクセラレーション機能がある。
D3DDEVCAPS_PUREDEVICE
デバイスは、ハードウェアでラスタ化、トランスフォーム、ライティング、およびシェーディングをサポートできる。
D3DDEVCAPS_QUINTICRTPATCHES
デバイスは、5 次ベジェおよび B スプラインをサポートしている。
D3DDEVCAPS_RTPATCHES
デバイスは、高次サーフェスをサポートする。
D3DDEVCAPS_RTPATCHHANDLEZERO
ハンドル値 0 を使って高次サーフェスを効率よく描画できることを示す。
D3DDEVCAPS_NPATCHES
デバイスは、N パッチをサポートする。

注意

これらのフラグは、組み合わせて、D3DCAPS8 の DevCaps メンバで使用できる。

参照

D3DCAPS8


CONST_D3DDEVTYPE

デバイスの種類を定義する。

Enum CONST_D3DDEVTYPE
    D3DDEVTYPE_HAL       = 1
    D3DDEVTYPE_REF       = 2
    D3DDEVTYPE_SW        = 3
End Enum

定数

D3DDEVTYPE_HAL
ラスタ化とシェーディングはハードウェアで行い、トランスフォームとライティングにはソフトウェア、ハードウェア、またはその両方を使用する。
D3DDEVTYPE_REF
Microsoft® Direct3D® の機能がソフトウェアに実装される。
D3DDEVTYPE_SW
Direct3D8.RegisterSoftwareDevice を使用して Direct3D に登録されたプラグ可能なソフトウェア デバイス。

参照

Direct3D8.CheckDeviceFormat、Direct3D8.CheckDeviceMultiSampleType、Direct3D8.CheckDeviceType、Direct3D8.CreateDevice、Direct3D8.GetDeviceCaps、D3DDEVICE_CREATION_PARAMETERS


CONST_D3DERR

システムで発生するエラー コードを定義する。これらのエラー コードの詳細については、「エラー コード」を参照すること。


CONST_D3DFILLMODE

塗りつぶしモードを記述する定数を定義する。

Enum CONST_D3DFILLMODE
    D3DFILL_POINT     = 1
    D3DFILL_WIREFRAME = 2
    D3DFILL_SOLID     = 3
End Enum

定数

D3DFILL_POINT
ポイントで塗りつぶす。
D3DFILL_WIREFRAME
ワイヤフレームで塗りつぶす。現在、この塗りつぶしモードは、DrawPrimitive メソッドの使用時、クリップされたプリミティブでは動作しない。
D3DFILL_SOLID
面で塗りつぶす。

注意

これらのフラグは、CONST_D3DRENDERSTATETYPE 列挙の D3DRS_FILLMODE レンダリング ステートの値を設定するために使われる。

参照

CONST_D3DRENDERSTATETYPE


CONST_D3DFOGMODE

フォグ モードを記述する定数を定義する。

Enum CONST_D3DFOGMODE
    D3DFOG_NONE   = 0
    D3DFOG_EXP    = 1
    D3DFOG_EXP2   = 2
    D3DFOG_LINEAR = 3
End Enum

定数

D3DFOG_NONE
フォグ エフェクトはない。
D3DFOG_EXP
次の方程式の指数で、フォグ エフェクトが増す。

D3DFOG_EXP2
次の方程式の指数の 2 乗で、フォグ エフェクトが増す。

D3DFOG_LINEAR
次の方程式の始点と終点の間で線形に、フォグ エフェクトが増す。

これは、現在サポートされている唯一のフォグ モードである。

注意

これらのフラグは、CONST_D3DRENDERSTATETYPE 列挙の D3DRS_FOGTABLEMODE および D3DRS_FOGVERTEXMODE の各レンダリング ステートの値を設定するために使われる。

フォグは、透明度を表す基準である。この場合、フォグの方程式によって生成されるフォグの値が小さいほど、オブジェクトは見えにくくなる。

参照

CONST_D3DRENDERSTATETYPE


CONST_D3DFORMAT

さまざまな種類のサーフェス フォーマットを定義する。

Enum CONST_D3DFORMAT
    D3DFMT_UNKNOWN       =   0
    D3DFMT_R8G8B8        =  20 (&H14)
    D3DFMT_A8R8G8B8      =  21 (&H15)
    D3DFMT_X8R8G8B8      =  22 (&H16)
    D3DFMT_R5G6B5        =  23 (&H17)
    D3DFMT_X1R5G5B5      =  24 (&H18)
    D3DFMT_A1R5G5B5      =  25 (&H19)
    D3DFMT_A4R4G4B4      =  26 (&H1A)
    D3DFMT_R3G3B2        =  27 (&H1B)
    D3DFMT_A8            =  28 (&H1C)
    D3DFMT_A8R3G3B2      =  29 (&H1D)
    D3DFMT_X4R4G4B4      =  30 (&H1E)
    D3DFMT_A8P8          =  40 (&H28)
    D3DFMT_P8            =  41 (&H29)
    D3DFMT_L8            =  50 (&H32)
    D3DFMT_A8L8          =  51 (&H33)
    D3DFMT_A4L4          =  52 (&H34)
    D3DFMT_V8U8          =  60 (&H3C)
    D3DFMT_L6V5U5        =  61 (&H3D)
    D3DFMT_X8L8V8U8      =  62 (&H3E)
    D3DFMT_Q8W8V8U8      =  63 (&H3F)
    D3DFMT_V16U16        =  64 (&H40)
    D3DFMT_W11V11U10     =  65 (&H41)
    D3DFMT_UYVY          = 1498831189 (&H59565955)
    D3DFMT_YUY2          =  844715353 (&H32595559)
    D3DFMT_DXT1          =  827611204 (&H31545844)
    D3DFMT_DXT2          =  844388420 (&H32545844)
    D3DFMT_DXT3          =  861165636 (&H33545844)
    D3DFMT_DXT4          =  877942852 (&H34545844)
    D3DFMT_DXT5          =  894720068 (&H35545844)
    D3DFMT_D16_LOCKABLE  =  70 (&H46)
    D3DFMT_D32           =  71 (&H47)
    D3DFMT_D15S1         =  73 (&H49)
    D3DFMT_D24S8         =  75 (&H4B)
    D3DFMT_D16           =  80 (&H50)
    D3DFMT_D24X8         =  77 (&H4D)
    D3DFMT_D24X4S4       =  79 (&H4F)
    D3DFMT_VERTEXDATA    = 100 (&H64)
    D3DFMT_INDEX16       = 101 (&H65)
    D3DFMT_INDEX32       = 102 (&H66)
End Enum

定数

D3DFMT_UNKNOWN
サーフェス フォーマットは不明である。
D3DFMT_R8G8B8
24 ビットの RGB ピクセル フォーマット。
D3DFMT_A8R8G8B8
アルファ付きの 32 ビット ARGB ピクセル フォーマット。
D3DFMT_X8R8G8B8
32 ビットの RGB ピクセル フォーマットで、そのうち 8 ビットは各色のために確保されている。
D3DFMT_R5G6B5
16 ビットの RGB ピクセル フォーマット。
D3DFMT_X1R5G5B5
16 ビットのピクセル フォーマットで、そのうち 5 ビットは各色のために確保されている。
D3DFMT_A1R5G5B5
16 ビットのピクセル フォーマットで、各色に 5 ビットが、アルファ (透過型テクセル) に 1 ビットが、それぞれ確保されている。
D3DFMT_A4R4G4B4
16 ビットの ARGB ピクセル フォーマット。
D3DFMT_R3G3B2
8 ビットの RGB テクスチャ フォーマット。
D3DFMT_A8
8 ビットのアルファのみ。
D3DFMT_A8R3G3B2
16 ビットの ARGB テクスチャ フォーマット。
D3DFMT_X4R4G4B4
16 ビットの RGB ピクセル フォーマットで、そのうち 4 ビットは各色のために確保されている。
D3DFMT_A8P8
サーフェスは、8 ビットのアルファが付いた 8 ビットのカラー インデックス付き。
D3DFMT_P8
サーフェスは、8 ビットのカラー インデックス付き。
D3DFMT_L8
8 ビットの輝度のみ。
D3DFMT_A8L8
16 ビットのアルファ輝度。
D3DFMT_A4L4
8 ビットのアルファ輝度。
D3DFMT_V8U8
16 ビットのバンプマップ フォーマット。
D3DFMT_L6V5U5
輝度付きの 16 ビット バンプマップ フォーマット。
D3DFMT_X8L8V8U8
輝度付きの 32 ビット バンプマップ フォーマットで、8 ビットは各要素のために確保されている。
D3DFMT_Q8W8V8U8
32 ビットのバンプマップ フォーマット。
D3DFMT_V16U16
32 ビットのバンプマップ フォーマット。
D3DFMT_W11V11U10
32 ビットのバンプマップ フォーマット。
D3DFMT_UYVY
UYVY フォーマット (PC98 準拠)。
D3DFMT_YUY2
YUY2 フォーマット (PC98 準拠)。
D3DFMT_DXT1
DXT1 圧縮テクスチャ フォーマット。
D3DFMT_DXT2
DXT2 圧縮テクスチャ フォーマット。
D3DFMT_DXT3
DXT3 圧縮テクスチャ フォーマット。
D3DFMT_DXT4
DXT4 圧縮テクスチャ フォーマット。
D3DFMT_DXT5
DXT5 圧縮テクスチャ フォーマット。
D3DFMT_D16_LOCKABLE
16 ビットの Z バッファ ビット深度。これはアプリケーションでロック可能なサーフェス フォーマットである。
D3DFMT_D32
32 ビットの Z バッファ ビット深度。
D3DFMT_D15S1
16 ビットの Z バッファ ビット深度で、15 ビットが深度チャネルに、1 ビットがステンシル チャネルに確保されている。
D3DFMT_D24S8
32 ビットの Z バッファ ビット深度で、24 ビットが深度チャネルに、8 ビットがステンシル チャネルに確保されている。
D3DFMT_D16
16 ビットの Z バッファ ビット深度。
D3DFMT_D24X8
32 ビットの Z バッファ ビット深度で、24 ビットが深度チャネルにに確保されている。
D3DFMT_D24X4S4
32 ビットの Z バッファ ビット深度で、24 ビットが深度チャネルに、4 ビットがステンシル チャネルに確保されている。
D3DFMT_VERTEXDATA
頂点バッファ サーフェスを記述する。
D3DFMT_INDEX16
16 ビットのインデックス バッファのビット深度。
D3DFMT_INDEX32
32 ビットのインデックス バッファのビット深度。

注意

レンダリング ターゲット フォーマットはD3DFMT_X1R5G5B5、D3DFMT_R5G6B5、D3DFMT_X8R8G8B8、および D3DFMT_A8R8G8B8 に制限されていることに注意すること。

ビット オーダーは、最上位ビット (MSB) が先頭である。したがって、D3DFMT_A8L8 は、この 2 バイト フォーマットの上位バイトがアルファであることを示している。

D3DFMT_D16_LOCKABLE を除くすべての深度ステンシル フォーマットは、ピクセル単位の特定のビット オーダーを指定しない。これらはアプリケーションでロックできないので、ドライバは深度チャネルあたり指定されたビット数より多くのビットを使用できる (ただし、ステンシル チャネルでは使用できない)。

ピクセル フォーマットは、不透明 Long 識別子によって示される。このような Long のフォーマットが選択されているのは、IHV で定義されている拡張フォーマットの表現を可能にし、確立されている FOURCC 方式を取り入れるためである。Microsoft® Direct3D® ランタイムが認識するフォーマット群は、D3DFORMAT で定義されている。

IHV で提供されるフォーマットおよび多くの FOURCC コードは、D3DFORMAT 列挙型の一覧には示されていないことに注意する必要がある。この列挙型のフォーマットは、ランタイムによって認められているポイントがほかのフォーマットと異なる。つまり、リファレンス ラスタライザは、これらの型のすべてで動作する。IHV 提供のフォーマットは、カード単位に個々の IHV によってサポートされる。

参照

Direct3D8.CheckDeviceFormat、FOURCC コード


CONST_D3DFVFCAPSFLAGS

柔軟な頂点フォーマットの能力を定義する。

Enum CONST_D3DFVFCAPSFLAGS
    D3DFVFCAPS_TEXCOORDCOUNTMASK  =   65535 (&HFFFF)
    D3DFVFCAPS_DONOTSTRIPELEMENTS =  524288 (&H80000)
    D3DFVFCAPS_PSIZE              = 1048576 (&H100000)
End Enum

定数

D3DFVFCAPS_TEXCOORDCOUNTMASK
D3DCAPS8 の FVFCaps メンバの下位 16 ビットをマスクする。結果を整数型の変数に設定し、デバイスが複数のテクスチャ ブレンディングで同時に使用できるテクスチャ座標セットの総数を計算する (1 つの頂点に最大 8 つの頂点座標セットを使用できるが、デバイスはブレンディングに指定された数のテクスチャ座標セットしか使用できない)。
D3DFVFCAPS_DONOTSTRIPELEMENTS
頂点要素は削除しない方がよい。つまり、頂点フォーマットが現在のレンダリング ステートで使用されない要素を含んでいても、頂点を再度生成する必要はない。この能力フラグが指定されていない場合、頂点フォーマットから不要な要素を削除すると、パフォーマンスが向上する。
D3DFVFCAPS_PSIZE
D3DFVFCAPS_PSIZE がない場合、デバイスはトランスフォーム前の頂点に対する D3DFVF_PSIZE をサポートしないことを示す。この場合、ベース ポイント サイズは常に D3DRS_POINTSIZE から使用される。この能力は、ソフトウェアの固定機能頂点処理にのみ適用される。ソフトウェア頂点処理を行うときには、常に D3DFVF_PSIZE がサポートされる。

頂点シェーダによって書き込まれる出力ポイント サイズが常にサポートされる。頂点シェーダの場合、入力は出力ポイント サイズに依る。

D3DFVF_PSIZE は、常にトランスフォーム後の頂点に対してサポートされる。D3DFVF_PSIZE の詳細については、「柔軟な頂点フォーマット フラグ」を参照すること。

注意

これらのフラグは、組み合わせて、D3DCAPS8 の FVFCaps メンバで使用できる

参照

D3DCAPS8


CONST_D3DFVFFLAGS

柔軟な頂点フォーマット フラグを定義する。

詳細については、「柔軟な頂点フォーマット フラグ」を参照すること。


CONST_D3DFVFTEXTUREFORMATS

柔軟な頂点フォーマットの記述内でテクスチャ座標フォーマットを識別するために使用するビット パターンを定義する。この列挙のメンバは、OR 演算子を使って、柔軟な頂点フォーマットの記述で組み合わせることができる。

Enum CONST_D3DFVFTEXTUREFORMATS
    D3DFVF_TEXTUREFORMAT1  =        3
    D3DFVF_TEXTUREFORMAT2  =        0
    D3DFVF_TEXTUREFORMAT3  =        1
    D3DFVF_TEXTUREFORMAT4  =        2
    D3DFVF_TEXCOORDSIZE1_0 =   196608 (&H30000)
    D3DFVF_TEXCOORDSIZE1_1 =   786432 (&HC0000)
    D3DFVF_TEXCOORDSIZE1_2 =  3145728 (&H300000)
    D3DFVF_TEXCOORDSIZE1_3 = 12582912 (&HC00000)
    D3DFVF_TEXCOORDSIZE2_0 =        0
    D3DFVF_TEXCOORDSIZE2_1 =        0
    D3DFVF_TEXCOORDSIZE2_2 =        0
    D3DFVF_TEXCOORDSIZE2_3 =        0
    D3DFVF_TEXCOORDSIZE3_0 =    65536 (&H10000)
    D3DFVF_TEXCOORDSIZE3_1 =   262144 (&H40000)
    D3DFVF_TEXCOORDSIZE3_2 =  1048576 (&H100000)
    D3DFVF_TEXCOORDSIZE3_3 =  4194304 (&H400000)
    D3DFVF_TEXCOORDSIZE4_0 =   131072 (&H20000)
    D3DFVF_TEXCOORDSIZE4_1 =   524288 (&H80000)
    D3DFVF_TEXCOORDSIZE4_2 =  2097152 (&H200000)
    D3DFVF_TEXCOORDSIZE4_3 =  8388608 (&H800000)
End Enum

定数

D3DFVF_TEXTUREFORMAT1 ～ D3DFVF_TEXTUREFORMAT4
テクスチャ座標フォーマットを識別するための 1、2、3、または 4 次元ビット マスクを計算するために使用できる値。「注意」を参照すること。
D3DFVF_TEXCOORDSIZE1_0 ～ D3DFVF_TEXCOORDSIZE4_3
これらのビット パターンは、特定の頂点について異なるサイズのテクスチャ座標フォーマットを指定する。TEXCOORDSIZEm_n は、m 座標を頂点フォーマットの (n+1) 番目の位置に関連付けることを指定する。

注意

D3DFVF_TEXTUREFORMAT1 から D3DFVF_TEXTUREFORMAT4 は、テクスチャ座標セットを定義する値の番号を指定する。D3DFVF_TEXTUREFORMAT1 は 1 次元座標を示し、D3DFVF_TEXTUREFORMAT2 は 2 次元座標を示し、という順に以下続く。次のサンプル関数は、特定のテクスチャ座標のセットで使用される要素の数を記述するビット パターンを作成する方法を示している。

'D3DFVF_TEXCOORDSIZE1_coordIndex と同じで、1 つの
'テクスチャ座標を、coordIndex で指定された頂点フォーマットで使用することを指定する。
Function D3DFVF_TEXCOORDSIZE1(coordIndex As Long) As Long
    D3DFVF_TEXCOORDSIZE1 = D3DFVF_TEXTUREFORMAT1 * 2 ^ ((coordIndex * 2) + 16)
End Function

'D3DFVF_TEXCOORDSIZE1_coordIndex と同じで、2 つの
'テクスチャ座標を、coordIndex で指定された頂点フォーマットで使用することを指定する。
Function D3DFVF_TEXCOORDSIZE2(coordIndex As Long) As Long
    D3DFVF_TEXCOORDSIZE2 = D3DFVF_TEXTUREFORMAT2
End Function

'D3DFVF_TEXCOORDSIZE1_coordIndex と同じで、3 つの
'テクスチャ座標を、coordIndex で指定された頂点フォーマットで使用することを指定する。
Function D3DFVF_TEXCOORDSIZE3(coordIndex As Long) As Long
    D3DFVF_TEXCOORDSIZE3 = D3DFVF_TEXTUREFORMAT3 * 2 ^ ((coordIndex * 2) + 16)
End Function

'D3DFVF_TEXCOORDSIZE1_coordIndex と同じで、4 つの
'テクスチャ座標を、coordIndex で指定された頂点フォーマットで使用することを指定する。
Function D3DFVF_TEXCOORDSIZE4(coordIndex As Long) As Long
    D3DFVF_TEXCOORDSIZE4 = D3DFVF_TEXTUREFORMAT4 * 2 ^ ((coordIndex * 2) + 16)
End Function

参照

柔軟な頂点フォーマット フラグ


CONST_D3DBASISTYPE

高次サーフェスの基本タイプを定義する。

Enum CONST_D3DBASISTYPE
    D3DBASIS_BEZIER      = 0
    D3DBASIS_BSPLINE     = 1
    D3DBASIS_INTERPOLATE = 2
End Enum

定数

D3DBASIS_BEZIER
入力頂点は、一連のベジェ パッチとして扱われる。指定する頂点の数は、3 + 1 で割りきれる数でなければならない。この条件を満たさないメッシュ部分はレンダリングされない。各呼び出しによってレンダリングされるサーフェスの内側にあるサブパッチの間は、完全に連続しているものと想定されている。作成されるサーフェス上にあることが保証されているのは、各サブパッチの隅にある頂点だけである。
D3DBASIS_BSPLINE
入力頂点は、B スプライン サーフェスの制御ポイントとして扱われる。レンダリングされる開口部の数は、その方向の開口部の数より 2 つ少ない。一般に、指定されている制御頂点は、生成されるサーフェスに含まれていない。
D3DBASIS_INTERPOLATE
指定されているすべての入力頂点をサーフェスが通過するよう、補間基準によってサーフェスが定義される。

注意

D3DBASISTYPE のメンバは、テッセレーションの間に行われる高次サーフェス プリミティブの評価において使われる式を指定している。

参照

D3DRECTPATCH_INFO、D3DTRIPATCH_INFO


CONST_D3DLIGHTTYPE

ライトの種類を定義する。

Enum CONST_D3DLIGHTTYPE
    D3DLIGHT_POINT       = 1
    D3DLIGHT_SPOT        = 2
    D3DLIGHT_DIRECTIONAL = 3
End Enum

定数

D3DLIGHT_POINT
光源はポイント ライトである。光は空間内のポイントを持ち、全方向に光を照射する。
D3DLIGHT_SPOT
ライトはスポット ライトである。このライトは、照射がコーン内に制限されるポイントを除いては、ポイント ライトに似ている。このライト タイプには、方向、およびコーンの形状を決めるその他のパラメータがいくつかある。これらのパラメータについては、「D3DLIGHT8 型」を参照すること。
D3DLIGHT_DIRECTIONAL
ライトはディレクショナル ライトである。これは無限大の距離でポイント ライトを用いることに等しい。

注意

ディレクショナル ライトはポイント ライトより処理は多少速いが、結果についてはポイント ライトの方が上である。スポット ライトは面白い視覚エフェクトを出すが、計算上負荷が高い。

参照

D3DLIGHT8


CONST_D3DLINECAPS

ロック フラグを定義する。

Enum CONST_D3DLINECAPS
    D3DLINECAPS_TEXTURE  =  1
    D3DLINECAPS_ZTEST    =  2
    D3DLINECAPS_BLEND=   =  4
    D3DLINECAPS_ALPHACMP =  8
    D3DLINECAPS_FOG      = 16 (&H10)
End Enum

定数

D3DLINECAPS_TEXTURE
テクスチャ マッピングをサポートする。
D3DLINECAPS_ZTEST
Z バッファ比較をサポートする。
D3DLINECAPS_BLEND
ソース ブレンディングをサポートする。
D3DLINECAPS_ALPHACMP
アルファ テスト比較をサポートする。
D3DLINECAPS_FOG
フォグをサポートする。


CONST_D3DLOCKFLAGS

ロッキング フラグを定義する。

Enum CONST_D3DLOCKFLAGS
    D3DLOCK_READONLY        =    16 (&H10)
    D3DLOCK_NOSYSLOCK       =  2048 (&H800)
    D3DLOCK_NOOVERWRITE     =  4096 (&H1000)
    D3DLOCK_DISCARD         =  8192 (&H2000)
    D3DLOCK_NO_DIRTY_UPDATE = 32768 (&H8000)
End Enum

定数

D3DLOCK_READONLY
アプリケーションはバッファに書き込まない。いくつかの最適化が有効になる。D3DLOCK_READONLY は D3DLOCK_DISCARD と共に指定することはできない。また、D3DUSAGE_WRITEONLY で作成された入力または頂点バッファで指定することもできない。
D3DLOCK_NOSYSLOCK
ビデオ メモリ ロックのデフォルトの動作は、システム全体のクリティカル セクションを確保し、ロックの期間中はディスプレイ モードが変化しないことを保証するというものである。このフラグを指定すると、システム全体のクリティカル セクションはロックの間保持されない。

ロック処理は若干負荷が高くなるが、システムは、マウス カーソルの移動といった他の動作を実行できる。このフラグは、それを行わないとシステムに悪影響を及ぼすソフトウェア レンダリングに対するバック バッファのロックのような、長期間のロックに役立つ。

D3DLOCK_NOOVERWRITE
フレームの開始以降、またはこのフラグが指定されていない最後のロック以降に描画処理の呼び出しの中で参照されたインデックスまたは頂点は、ロック中に変更されないことを示す。インデックス バッファまたは頂点バッファへのデータの追加を行う場合のみ、このフラグにより処理を最適化できる。このフラグは、D3DUSAGE_DYNAMIC で作成されたバッファでのみ有効である。
D3DLOCK_DISCARD
書き込み専用で、アプリケーションはバッファ全体を上書きする。これにより、Direct3D は新しいメモリ領域へのポインタを返すことができ、ダイナミック メモリ アクセス (DMA) および古い領域からのレンダリングが機能停止しなくなる。このフラグは、インデックスおよび頂点バッファに対してのみ有効である。このフラグは、D3DUSAGE_DYNAMIC で作成されたバッファでのみ有効である。
D3DLOCK_NO_DIRTY_UPDATE
デフォルトでは、リソースをロックすると、そのリソースにダーティー領域が追加される。このフラグを指定すると、リソースのダーティー状態が変更されなくなる。アプリケーションでは、ロック処理の間に変更される実際の領域セットについての追加情報を持っているときは、このフラグを使用する必要がある。このフラグは、頂点バッファおよびインデックス バッファについては有効ではないことに注意すること。


CONST_D3DMATERIALCOLORSOURCE

ライティング計算のために参照しなければならない色または色成分の場所を定義する。

Enum CONST_D3DMATERIALCOLORSOURCE
    D3DMCS_MATERIAL = 0
    D3DMCS_COLOR1   = 1
    D3DMCS_COLOR2   = 2
End Enum

定数

D3DMCS_MATERIAL
現在のマテリアルの色を使用する。
D3DMCS_COLOR1
ディフューズ頂点カラーを使用する。
D3DMCS_COLOR2
スペキュラ頂点カラーを使用する。

注意

これらのフラグは、CONST_D3DRENDERSTATETYPE 列挙の以下のレンダリング ステートの値を設定するために使われる。

  • D3DRS_DIFFUSEMATERIALSOURCE
  • D3DRS_SPECULARMATERIALSOURCE
  • D3DRS_AMBIENTMATERIALSOURCE
  • D3DRS_EMISSIVEMATERIALSOURCE

参照

CONST_D3DRENDERSTATETYPE


CONST_D3DMULTISAMPLE_TYPE

デバイスが対応するフルシーン マルチサンプリングのレベルを定義する。

Enum CONST_D3DMULTISAMPLE_TYPE
    D3DMULTISAMPLE_NONE       =  0
    D3DMULTISAMPLE_2_SAMPLES  =  2
    D3DMULTISAMPLE_3_SAMPLES  =  3
    D3DMULTISAMPLE_4_SAMPLES  =  4
    D3DMULTISAMPLE_5_SAMPLES  =  5
    D3DMULTISAMPLE_6_SAMPLES  =  6
    D3DMULTISAMPLE_7_SAMPLES  =  7
    D3DMULTISAMPLE_8_SAMPLES  =  8
    D3DMULTISAMPLE_9_SAMPLES  =  9
    D3DMULTISAMPLE_10_SAMPLES = 10
    D3DMULTISAMPLE_11_SAMPLES = 11
    D3DMULTISAMPLE_12_SAMPLES = 12
    D3DMULTISAMPLE_13_SAMPLES = 13
    D3DMULTISAMPLE_14_SAMPLES = 14
    D3DMULTISAMPLE_15_SAMPLES = 15
    D3DMULTISAMPLE_16_SAMPLES = 16 (&H10)
End Enum

定数

D3DMULTISAMPLE_NONE
いずれのレベルのフルスクリーン マルチサンプリングも利用できない。
D3DMULTISAMPLE_2_SAMPLES ～ D3DMULTISAMPLE_16_SAMPLES
そのレベルのフルスクリーン マルチサンプリングを利用できる。

注意

Direct3DDevice8.Reset の呼び出し時にフルシーン マルチサンプリングを有効にできるだけでなく、さまざまな機能のオンまたはオフをきめ細かいレベルで設定するレンダリング ステートが用意されている。

マルチサンプリングは、D3DSWAPEFFECT_DISCARD スワップ エフェクトで作成またはリセットしているスワップ チェーンでのみ有効である。

参照

Direct3D8.CheckDeviceMultiSampleType、Direct3DDevice8.CreateDepthStencilSurface、Direct3DDevice8.CreateRenderTarget、D3DPRESENT_PARAMETERS、D3DSURFACE_DESC


CONST_D3DORDERTYPE

高次サーフェスのタイプを定義する。

Enum CONST_D3DORDERTYPE
    D3DORDER_LINEAR    = 1
    D3DORDER_CUBIC     = 3
    D3DORDER_QUINTIC   = 5
End Enum

定数

D3DORDER_LINEAR
線形タイプである。
D3DORDER_CUBIC
3 次タイプである。
D3DORDER_QUINTIC
5 次タイプである。

参照

D3DRECTPATCH_INFO、D3DTRIPATCH_INFO


CONST_D3DPBLENDCAPSFLAGS

ソース ブレンディング能力を定義する。

Enum CONST_D3DPBLENDCAPSFLAGS
    D3DPBLENDCAPS_ZERO            =    1
    D3DPBLENDCAPS_ONE             =    2
    D3DPBLENDCAPS_SRCCOLOR        =    4
    D3DPBLENDCAPS_INVSRCCOLOR     =    8
    D3DPBLENDCAPS_SRCALPHA        =   16 (&H10)
    D3DPBLENDCAPS_INVSRCALPHA     =   32 (&H20)
    D3DPBLENDCAPS_DESTALPHA       =   64 (&H40)
    D3DPBLENDCAPS_INVDESTALPHA    =  128 (&H80)
    D3DPBLENDCAPS_DESTCOLOR       =  256 (&H100)
    D3DPBLENDCAPS_INVDESTCOLOR    =  512 (&H200)
    D3DPBLENDCAPS_SRCALPHASAT     = 1024 (&H400)
    D3DPBLENDCAPS_BOTHSRCALPHA    = 2048 (&H800)
    D3DPBLENDCAPS_BOTHINVSRCALPHA = 4096 (&H1000)
End Enum

定数

D3DPBLENDCAPS_ZERO
ブレンディング係数は、(0, 0, 0, 0)。
D3DPBLENDCAPS_ONE
ブレンディング係数は、(1, 1, 1, 1)。
D3DPBLENDCAPS_SRCCOLOR
ブレンディング係数は、(Rs, Gs, Bs, As)。
D3DPBLENDCAPS_INVSRCCOLOR
ブレンディング係数は、(1-Rd, 1-Gd, 1-Bd, 1-Ad)。
D3DPBLENDCAPS_SRCALPHA
ブレンディング係数は、(As, As, As, As)。
D3DPBLENDCAPS_INVSRCALPHA
ブレンディング係数は、(1-As, 1-As, 1-As, 1-As)。
D3DPBLENDCAPS_DESTALPHA
ブレンディング係数は、(Ad, Ad, Ad, Ad)。
D3DPBLENDCAPS_INVDESTALPHA
ブレンディング係数は、(1-Ad, 1-Ad, 1-Ad, 1-Ad)。
D3DPBLENDCAPS_DESTCOLOR
ブレンディング係数は、(Rd, Gd, Bd, Ad)。
D3DPBLENDCAPS_INVDESTCOLOR
ブレンディング係数は、(1-Rd, 1-Gd, 1-Bd, 1-Ad)。
D3DPBLENDCAPS_SRCALPHASAT
ブレンディング係数は (f, f, f, 1)、f = min(As, 1-Ad)。
D3DPBLENDCAPS_BOTHSRCALPHA
ドライバは D3DBLEND_BOTHSRCALPHA ブレンディング モードをサポートする(このブレンディング モードは廃止されている。詳細については、「CONST_D3DBLEND」を参照すること。)
D3DPBLENDCAPS_BOTHINVSRCALPHA
ソース ブレンディング係数は、(1-As, 1-As, 1-As, 1-As)。デスティネーション ブレンディング係数は、(As, As, As, As)。デスティネーションのブレンディングの選択は無効になる。

注意

転送元および転送先の RGBA 値は、添字の s および d で示される。

この列挙型の値は、D3DPRIMCAPS8 の SrcBlendCaps メンバに対する値を定義している。

参照

D3DCAPS8


CONST_D3DPATCHEDGESTYLE

ソース ブレンディング能力を定義する。

Enum CONST_D3DPATCHEDGESTYLE
    D3DPATCHEDGE_DISCRETE = 0,
    D3DPATCHEDGE_CONTINUOUS = 1
End Enum

定数

D3DPATCHEDGE_DISCRETE
個別エッジ スタイル。個別モードでは、浮動小数点数のテッセレーションを指定できるが、整数に切り詰められる。
D3DPATCHEDGE_CONTINUOUS
連続エッジ スタイル。連続モードでは、テッセレーションは浮動小数点数値として指定され、なめらかに変化させて不自然な効果「ポッピング」を減少させることができる。

注意

連続テッセレーションでは、テッセレーションの値が同じでも、個別テッセレーションとはまったく異なるテッセレーション パターンが生成されることに注意すること (これはワイヤフレーム モードでより顕著になる)。したがって、連続モードの 4.0 は個別モードの 4 と同じではない。


CONST_D3DPCMPCAPSFLAGS

比較能力を定義する。

Enum CONST_D3DPCMPCAPSFLAGS
    D3DPCMPCAPS_NEVER        =   1
    D3DPCMPCAPS_LESS         =   2
    D3DPCMPCAPS_EQUAL        =   4
    D3DPCMPCAPS_LESSEQUAL    =   8
    D3DPCMPCAPS_GREATER      =  16 (&H10)
    D3DPCMPCAPS_NOTEQUAL     =  32 (&H20)
    D3DPCMPCAPS_GREATEREQUAL =  64 (&H40)
    D3DPCMPCAPS_ALWAYS       = 128 (&H80)
End Enum

定数

D3DPCMPCAPS_NEVER
常にテストは失敗する。
D3DPCMPCAPS_LESS
新規の値が現在の値より小さい場合、テストはパスする。
D3DPCMPCAPS_EQUAL
新規の値が現在の値と等しい場合、テストはパスする。
D3DPCMPCAPS_LESSEQUAL
新規の値が現在の値より小さいか等しい場合、テストはパスする。
D3DPCMPCAPS_GREATER
新規の値が現在の値より大きい場合、テストはパスする。
D3DPCMPCAPS_NOTEQUAL
新規の値が現在の値と異なる場合、テストはパスする。
D3DPCMPCAPS_GREATEREQUAL
新規の値が現在の値より大きいか等しい場合、テストはパスする。
D3DPCMPCAPS_ALWAYS
常にテストはパスする。

注意

この列挙型の値は、D3DCAPS8 の AlphaCmpCaps メンバおよび ZCmpCaps メンバに対してサポートされている比較関数を定義している。

参照

D3DCAPS8


CONST_D3DPMISCCAPSFLAGS

このプリミティブの総合的な能力を定義する。

Enum CONST_D3DPMISCCAPSFLAGS
    D3DPMISCCAPS_MASKZ                 =    2
    D3DPMISCCAPS_LINEPATTERNREP        =    4
    D3DPMISCCAPS_CULLNONE              =   16 (&H10)
    D3DPMISCCAPS_CULLCW                =   32 (&H20)
    D3DPMISCCAPS_CULLCCW               =   64 (&H40)
    D3DPMISCCAPS_COLORWRITEENABLE      =  128 (&H80)
    D3DPMISCCAPS_CLIPPLANESCALEDPOINTS =  256 (&H100)
    D3DPMISCCAPS_CLIPTLVERTS           =  512 (&H200)
    D3DPMISCCAPS_TSSARGTEMP            = 1024 (&H400)
    D3DPMISCCAPS_BLENDOP               = 2048 (&H800)
End Enum

定数

D3DPMISCCAPS_MASKZ
デバイスは、ピクセル処理での深度バッファの変更を有効にしたり、無効にしたりできる。
D3DPMISCCAPS_LINEPATTERNREP
ドライバは、D3DLINEPATTERN 型の RepeatFactor メンバで 1 以外の値を処理できる (これは線描画プリミティブにのみ適用される)。
D3DPMISCCAPS_CULLNONE
ドライバは、三角形カリングを実行しない。CONST_D3DCULL 列挙の D3DCULL_NONE メンバに対応する。
D3DPMISCCAPS_CULLCW
ドライバは、D3DRS_CULLMODE ステートを使用して時計回りの三角形カリングをサポートする (三角形のプリミティブの場合のみ)。CONST_D3DCULL 列挙のD3DCULL_CW メンバに対応する。
D3DPMISCCAPS_CULLCCW
ドライバは、D3DRS_CULLMODE ステートを使用して反時計回りのカリングをサポートする (三角形のプリミティブの場合のみ)。CONST_D3DCULL 列挙の D3DCULL_CCW メンバに対応する。
D3DPMISCCAPS_COLORWRITEENABLE
デバイスは、D3DRS_COLORWRITEENABLE ステートを使用して、レンダリング ターゲットのカラー バッファに対するチャネルごとの書き込みをサポートする。
D3DPMISCCAPS_CLIPPLANESCALEDPOINTS
デバイスは、正確に、1.0 より大きいサイズのスケーリングされたポイントを、ユーザー定義クリップ面にクリップする。
D3DPMISCCAPS_CLIPTLVERTS
デバイスは、トランスフォーム後の頂点プリミティブをクリップする。
D3DPMISCCAPS_TSSARGTEMP
デバイスは、テンポラリ レジスタの D3DTA_TEMP をサポートする。
D3DPMISCCAPS_BLENDOP
デバイスは、CONST_D3DBLENDOP 列挙型に定義されるアルファ ブレンディング処理をサポートする。

注意

MiscCaps

この列挙の値は、D3DCAPS8 の PrimitiveMiscCaps メンバに対する値を定義している。

参照

D3DCAPS8


CONST_D3DPOOL

リソースのバッファを保持するメモリ クラスを定義する。

Enum CONST_D3DPOOL
    D3DPOOL_DEFAULT        = 0
    D3DPOOL_MANAGED        = 1
    D3DPOOL_SYSTEMMEM      = 2
End Enum

定数

D3DPOOL_DEFAULT
リソースは、リソースに対して要求された使用方法に最も適したメモリ プールに置かれる。これは、通常、ローカル ビデオ メモリと AGP メモリの両方を含む、ビデオ メモリである。D3DPOOL_DEFAULT プールは D3DPOOL_MANAGED および D3DPOOL_SYTEMMEM から独立しており、リソースがデバイス アクセス用の優先メモリに配置されることを指定する。D3DPOOL_DEFAULT は、このリソースのメモリ プール タイプとして D3DPOOL_MANAGED または D3DPOOL_SYSTEMMEM のいずれかを選択しなければならないことを示しているのではないことに注意すること。D3DPOOL_DEFAULT プールに配置されたテクスチャは、ロックできないので、直接アクセスできない。代わりに、Direct3DDevice8.CopyRects や Direct3dDevice8.UpdateTexture などの関数を使用しなければならない。D3DPOOL_MANAGED は、ほとんどのアプリケーションで D3DPOOL_DEFAULT よりも適している場合が多い。Direct3D ランタイムでは未知の、ドライバ独自のピクセル フォーマットで作成されたテクスチャの一部はロックできることに注意すること。また、テクスチャと異なり、スワップチェーン バックバッファ、レンダリング ターゲット、頂点バッファ、およびインデックス バッファはロックできることにも注意すること。

デバイスが消失した場合は、D3DPOOL_DEFAULT を使って作成したリソースは、Direct3DDevice8.Reset を呼び出す前に解放しなければならない。詳細については、「消失したデバイス」を参照すること。

D3DPOOL_MANAGED
リソースは、必要に応じて、デバイスからアクセスできるメモリに自動的にコピーされる。管理リソースは、システム メモリにバックアップされるので、デバイスが消失したときに作成し直す必要がない。詳細については、「リソースの管理」を参照すること。管理リソースはロックできる。システム メモリのコピーだけが直接変更される。Direct3D は、必要に応じて、ドライバがアクセス可能なメモリに変更内容をコピーする。
D3DPOOL_SYSTEMMEM
通常 3D デバイスによってアクセスできないメモリ。このフラグはシステム RAM を使用するが、ページング可能な RAM が減ることはない。これらのリソースは、デバイスが消失しても作成し直す必要がない。このプールのリソースはロックすることができ、D3DPOOL_DEFAULT を使って作成されたメモリ リソースに対する Direct3DDevice8.CopyRects または Direct3DDevice8.UpdateTexture 処理の転送元として使用できる。

注意

1 つのリソース (ミップマップのミップ レベル) に含まれる異なるオブジェクトに対して複数のプールを混在させることはできず、いったん選択したプールは変更できない。

ほとんどの静的リソースに対しては D3DPOOL_MANAGED を使用する必要がある。これは、アプリケーションを消失したデバイスの処理と切り離すからである。管理リソースはランタイムによって復元される。これは、特に UMA システムで有効である。また、ダイナミック テクスチャ リソースに対しても、その変更頻度の多さにかかわらず、D3DPOOL_MANAGED を使用するとよい。それ以外の動的リソースに対しては、D3DPOOL_MANAGED は使用しない方がよい。実際、D3DPOOL_MANAGED と D3DUSAGE_DYNAMIC を共に使用して、インデックス バッファおよび頂点バッファを作成することはできない。

ダイナミック テクスチャの場合は、ビデオ メモリとシステム メモリのテクスチャのペアを使用して、D3DPOOL_DEFAULT を使ってビデオ メモリを、D3DPOOL_SYSTEMMEM を使ってシステム メモリを割り当てることがある。ロッキング メソッドを使って、システム メモリ テクスチャのビットをロックおよび変更できる。その後、Direct3DDevice8.UpdateTexture を使用して、ビデオ メモリ テクスチャを更新できる。

参照

Direct3DDevice8.CreateCubeTexture、Direct3DDevice8.CreateIndexBuffer、Direct3DDevice8.CreateTexture、Direct3DDevice8.CreateVertexBuffer、Direct3DDevice8.CreateVolumeTexture、D3DINDEXBUFFER_DESC、D3DSURFACE_DESC、D3DVERTEXBUFFER_DESC、D3DVOLUME_DESC


CONST_D3DPRASTERCAPSFLAGS

ラスタ描画の能力情報についての情報を提供する定数を定義する。

Enum CONST_D3DPRASTERCAPSFLAGS
    D3DPRASTERCAPS_DITHER                     =       1
    D3DPRASTERCAPS_PAT                        =       8
    D3DPRASTERCAPS_ZTEST                      =      16 (&H10)
    D3DPRASTERCAPS_FOGVERTEX                  =     128 (&H80)
    D3DPRASTERCAPS_FOGTABLE                   =     256 (&H100)
    D3DPRASTERCAPS_ANTIALIASEDGES             =    4096 (&H1000)
    D3DPRASTERCAPS_MIPMAPLODBIAS              =    8192 (&H2000)
    D3DPRASTERCAPS_ZBIAS                      =   16384 (&H4000)
    D3DPRASTERCAPS_ZBUFFERLESSHSR             =   32768 (&H8000)
    D3DPRASTERCAPS_FOGRANGE                   =   65536 (&H10000)
    D3DPRASTERCAPS_ANISOTROPY                 =  131072 (&H20000)
    D3DPRASTERCAPS_WBUFFER                    =  262144 (&H40000)
    D3DPRASTERCAPS_WFOG                       = 1048576 (&H100000)
    D3DPRASTERCAPS_ZFOG                       = 2097152 (&H200000)
    D3DPRASTERCAPS_COLORPERSPECTIVE           = 4194304 (&H400000)
    D3DPRASTERCAPS_STRETCHBLTMULTISAMPLE      = 8388608 (&H800000)
End Enum

定数

D3DPRASTERCAPS_DITHER
デバイスは、色の再現力を良くするためにディザ表示できる。
D3DPRASTERCAPS_PAT
ドライバは、照会されているプリミティブに対し、D3DRS_LINEPATTERN を使った線や塗りつぶしのパターン描画を実行できる。
D3DPRASTERCAPS_ZTEST
デバイスは Z テスト処理を実行できる。この値は、効果的にプリミティブをレンダリングし、Z ピクセルがレンダリングされたかどうかを示す。
D3DPRASTERCAPS_FOGVERTEX
デバイスはライティング処理の間フォグ値を計算し、D3DTLVERTEX 型の specular メンバのアルファ成分中に値を格納し、ラスタの間フォグ値を補間する。
D3DPRASTERCAPS_FOGTABLE
デバイスは、ピクセルの深さを指すフォグ値を含む参照テーブルと照合して、フォグ値を算出する。
D3DPRASTERCAPS_ANTIALIASEDGES
デバイスは、オブジェクトの輪郭線が凸状になるようなアンチエイリアス線を作ることができる。詳細については、CONST_D3DRENDERSTATETYPE 列挙の「D3DRS_EDGEANTIALIAS」を参照すること。
D3DPRASTERCAPS_MIPMAPLODBIAS
デバイスは詳細レベル (LOD) バイアス調整をサポートする。これらのバイアス調整により、ミップマップを普通よりもすっきりと、またはあまり鋭くなく見せることができる。ミップマップの LOD バイアスの詳細については、「D3DTSS_MIPMAPLODBIAS」を参照すること。
D3DPRASTERCAPS_ZBIAS
デバイスは z バイアス値をサポートする。これらはポリゴンに割り当てられた整数値であり、物理的に同一平面上にあるポリゴンを別々に表示する。詳細については、CONST_D3DRENDERSTATETYPE 列挙の「D3DRS_ZBIAS」を参照すること。
D3DPRASTERCAPS_ZBUFFERLESSHSR
デバイスは、隠面の除去 (HRS) を実行でき、このとき、ポリゴンのソートや深度バッファの割り当てを必要としない。これにより、より多くのビデオ メモリをテクスチャ用に使うことができる。HSR を実行するために使用するメソッドはハードウェアの機能に依存し、アプリケーションに対しては透過的である。

Z バッファなしの HRS が実行されるのは、深度バッファ サーフェスがレンダリング ターゲット サーフェスに関連付けられておらず、かつ深度バッファの比較テストが有効になっている場合 (つまり、D3DRS_ZENABLE 列挙定数に関連付けられたステート値が TRUE に設定されている場合) である。

D3DPRASTERCAPS_FOGRANGE
デバイスは範囲ベースのフォグをサポートする。範囲ベースのフォグでは、シーンにおけるオブジェクトの深度 (z 座標) ではなく、ビューアからのオブジェクトの距離でフォグ エフェクトを計算する。詳細については、「範囲ベースのフォグ」を参照すること。
D3DPRASTERCAPS_ANISOTROPY
デバイスは異方性 (anisotropic) フィルタリングをサポートする。
D3DPRASTERCAPS_WBUFFER
デバイスは、w を使用して深度バッファリングをサポートする。詳細については、「深度バッファ」を参照すること。
D3DPRASTERCAPS_WFOG
デバイスは w ベースのフォグをサポートする。w ベースのフォグはパースペクティブ射影行列が指定された場合に使用されるが、アフィン射影では現在でも z ベース・フォグを使用する。システムは、[3][4] 要素がゼロ以外の値を持つ射影行列をパースペクティブ射影行列であると見なす。
D3DPRASTERCAPS_ZFOG
デバイスは z ベースのフォグをサポートする。
D3DPRASTERCAPS_COLORPERSPECTIVE
デバイスは、色パースペクティブ補正を補間する。
D3DPRASTERCAPS_STRETCHBLTMULTISAMPLE
デバイスは、blt メソッドの拡大を実装することで、制限されたマルチサンプルのサポートを提供する。この能力が設定されている場合、シーンの途中で D3DRS_MULTISAMPLEANTIALIAS のオンとオフを切り替えることはできない。このフラグが設定されている場合、マルチサンプル マスキングは実行できない。

注意

これらのフラグは、組み合わせて、D3DCAPS8 の RasterCaps メンバで使用できる。

参照

D3DCAPS8


CONST_D3DPRESENT_INTERVAL_FLAGS

スワップ チェーンのバック バッファをプレゼンテーションできる最大レート。

Enum CONST_D3DPRESENT_INTERVAL_FLAGS
    D3DPRESENT_INTERVAL_DEFAULT   =            0
    D3DPRESENT_INTERVAL_ONE       =            1
    D3DPRESENT_INTERVAL_TWO       =            2
    D3DPRESENT_INTERVAL_THREE     =            4
    D3DPRESENT_INTERVAL_FOUR      =            8
    D3DPRESENT_INTERVAL_IMMEDIATE =  -2147483648 (&H80000000)
End Enum

定数

D3DPRESENT_INTERVAL_DEFAULT
ドライバは、デフォルトのプレゼンテーション間隔をサポートしている。
D3DPRESENT_INTERVAL_ONE
ドライバは垂直帰線間隔を待つ。プレゼンテーション処理への影響は、スクリーン リフレッシュほど頻繁ではない。
D3DPRESENT_INTERVAL_TWO
ドライバは垂直帰線間隔を待つ。プレゼンテーション処理への影響は、スクリーン リフレッシュ (1 回おき) ほど頻繁ではない。
D3DPRESENT_INTERVAL_THREE
ドライバは垂直帰線間隔を待つ。プレゼンテーション処理への影響は、スクリーン リフレッシュ (2 回おき) ほど頻繁ではない。
D3DPRESENT_INTERVAL_FOUR
ドライバは垂直帰線間隔を待つ。プレゼンテーション処理への影響は、スクリーン リフレッシュ (3 回おき) ほど頻繁ではない。
D3DPRESENT_INTERVAL_IMMEDIATE
プレゼンテーション処理に直接影響する場合がある。ドライバは垂直帰線間隔を待たない。

注意

ウィンドウ スワップ チェーンの場合、この値は D3DPRESENT_INTERVAL_DEFAULT (0) でなければならない。フルスクリーン スワップ チェーンの場合は、D3DPRESENT_INTERVAL_DEFAULT、または D3DCAPS8 の PresentationIntervals メンバに列挙されるいずれかのフラグに対応する値を設定できる。

参照

D3DCAPS8


CONST_D3DPRESENT_RATE_FLAGS

フレームを出力に提示できる最大速度を定義する。

Enum CONST_D3DPRESENT_RATE_FLAGS
    D3DPRESENT_RATE_DEFAULT   =          0
    D3DPRESENT_RATE_UNLIMITED = 2147483647 (&H7FFFFFFF)
End Enum

定数

D3DPRESENT_RATE_UNLIMITED
プレゼンテーション速度は、ハードウェアがフレームを提供できる速さで動作する。
D3DPRESENT_RATE_DEFAULT
Microsoft® Direct3D® は、プレゼンテーション速度を選択する。または、ウィンドウ モードの場合は現在の速度を使用する。

注意

D3DPRESENT_PARAMETERS の FullScreen_RefreshRateInHz メンバでは、これらの値のいずれかを指定できる。

参照

D3DPRESENT_PARAMETERS


CONST_D3DPRIMITIVETYPE

Microsoft® Direct3D® がサポートするプリミティブを定義する。

Enum CONST_D3DPRIMITIVETYPE
    D3DPT_POINTLIST     = 1
    D3DPT_LINELIST      = 2
    D3DPT_LINESTRIP     = 3
    D3DPT_TRIANGLELIST  = 4
    D3DPT_TRIANGLESTRIP = 5
    D3DPT_TRIANGLEFAN   = 6
End Enum

定数

D3DPT_POINTLIST
別個のポイントの集合として頂点をレンダリングする。
D3DPT_LINELIST
別個の線分のリストとして頂点をレンダリングする。このプリミティブ タイプを使用する呼び出しは、カウントが 2 より小さいか、奇数の場合は失敗する。
D3DPT_LINESTRIP
単一のポリラインとして頂点をレンダリングする。このプリミティブ タイプを使用する呼び出しは、カウントが 2 より小さい場合は失敗する。
D3DPT_TRIANGLELIST
別個の三角形の連続として指定の頂点をレンダリングする。各 3 頂点のグループは個別に三角形を定義する。

裏面のカリングは、現在のカリング モード レンダリング ステートの影響を受ける。

D3DPT_TRIANGLESTRIP
頂点を三角形ストリップとしてレンダリングする。背面カリング フラグは、偶数番号の三角形で自動的に反転する。
D3DPT_TRIANGLEFAN
頂点を三角形ファンとしてレンダリングする。

注意

三角形ストリップまたは三角形ファンを使用する方が、三角形リストを使用するより効率がよい。詳細については、「三角形ストリップ」および「三角形ファン」を参照すること。

参照

Direct3DDevice8.DrawIndexedPrimitive、Direct3DDevice8.DrawIndexedPrimitiveUP、Direct3DDevice8.DrawPrimitive、Direct3DDevice8.DrawPrimitiveUP


CONST_D3DPSHADECAPSFLAGS

シェーディング処理能力を定義する。

Enum CONST_D3DPSHADECAPSFLAGS
    D3DPSHADECAPS_COLORGOURAUDRGB      =       8
    D3DPSHADECAPS_SPECULARGOURAUDRGB   =     512 (&H200)
    D3DPSHADECAPS_ALPHAGOURAUDBLEND    =   16384 (&H4000)
    D3DPSHADECAPS_FOGGOURAUD           =  524288 (&H80000)
End Enum

定数

D3DPSHADECAPS_COLORGOURAUDRGB
デバイスは、RGB カラー モデルでカラー グーロー シェーディングをサポートできる。このモードでは、プリミティブに対する色成分は頂点で与えられて、ほかの色成分と共に面に沿って補間される。RGB ライティング モデルでは、赤、緑、および青の各成分が補間される。
D3DPSHADECAPS_SPECULARGOURAUDRGB
デバイスは、RGB カラー モデルのグーロー シェーディングにおいてスペキュラ ハイライトをサポートできる。
D3DPSHADECAPS_ALPHAGOURAUDBLEND
デバイスは、グーロー ブレンドによる透明化 (CONST_D3DSHADEMODE 列挙の D3DSHADE_GOURAUD ステート) に対するアルファ成分をサポートできる。このモードでは、プリミティブのアルファ成分は頂点で与えられて、ほかの色成分と共に面に沿って補間される。
D3DPSHADECAPS_FOGGOURAUD
デバイスは、グーロー シェーディング モードでフォグをサポートできる。

注意

これらのフラグは、組み合わせて、D3DCAPS8 の ShadeCaps メンバで使用できる。

参照

D3DCAPS8


CONST_D3DPTADDRESSCAPSFLAGS

テクスチャのアドレス能力を定義する。

Enum CONST_D3DPTADDRESSCAPSFLAGS
    D3DPTADDRESSCAPS_WRAP          =  1
    D3DPTADDRESSCAPS_MIRROR        =  2
    D3DPTADDRESSCAPS_CLAMP         =  4
    D3DPTADDRESSCAPS_BORDER        =  8
    D3DPTADDRESSCAPS_INDEPENDENTUV = 16 (&H10)
    D3DPTADDRESSCAPS_MIRRORONCE    = 32 (&H20)
End Enum

定数

D3DPTADDRESSCAPS_WRAP
デバイスは、テクスチャの張り付けが可能である。
D3DPTADDRESSCAPS_MIRROR
デバイスは、テクスチャをアドレスに反映させることができる。
D3DPTADDRESSCAPS_CLAMP
デバイスは、テクスチャをアドレスに固定できる。
D3DPTADDRESSCAPS_BORDER
デバイスは、D3DTSS_BORDERCOLOR テクスチャ ステージ ステートで指定される境界色を、[0.0, 1.0] の範囲外の座標に設定できる。
D3DPTADDRESSCAPS_INDEPENDENTUV
デバイスは、テクスチャの U 座標と V 座標のテクスチャ アドレッシング モードを分離できる。この能力は、D3DTSS_ADDRESSU および D3DTSS_ADDRESSV レンダリング ステート値に対応する。
D3DPTADDRESSCAPS_MIRRORONCE
デバイスは、テクスチャ座標の絶対値を取得し (0 を中心にミラーリング)、最大値に制限する。

注意

これらのフラグは、組み合わせて、D3DCAPS8 の TextureAddressCaps メンバで使用できる。

参照

D3DCAPS8


CONST_D3DPTEXTURECAPSFLAGS

その他のテクスチャ マッピング能力を定義する。

Enum CONST_D3DPTEXTURECAPSFLAGS
    D3DPTEXTURECAPS_PERSPECTIVE              =      1
    D3DPTEXTURECAPS_POW2                     =      2
    D3DPTEXTURECAPS_ALPHA                    =      4
    D3DPTEXTURECAPS_SQUAREONLY               =     32 (&H20)
    D3DPTEXTURECAPS_TEXREPEATNOTSCALEDBYSIZE =     64 (&H40)
    D3DPTEXTURECAPS_ALPHAPALETTE             =    128 (&H80)
    D3DPTEXTURECAPS_NONPOW2CONDITIONAL       =    256 (&H100)
    D3DPTEXTURECAPS_PROJECTED                =   1024 (&H400)
    D3DPTEXTURECAPS_CUBEMAP                  =   2048 (&H800)
    D3DPTEXTURECAPS_VOLUMEMAP                =   8192 (&H2000)
    D3DPTEXTURECAPS_MIPMAP                   =  16384 (&H4000)
    D3DPTEXTURECAPS_MIPVOLUMEMAP             =  32768 (&H8000)
    D3DPTEXTURECAPS_MIPCUBEMAP               =  65536 (&H10000)
    D3DPTEXTURECAPS_CUBEMAP_POW2             = 131072 (&H20000)
    D3DPTEXTURECAPS_VOLUMEMAP_POW2           = 262144 (&H40000)
End Enum

定数

D3DPTEXTURECAPS_PERSPECTIVE
パースペクティブ補正のテクスチャリングがサポートされる。
D3DPTEXTURECAPS_POW2
すべてのテクスチャの幅と高さは、2 の累乗で指定されていなければならない。この条件は、キューブ テクスチャまたはボリューム テクスチャには適用されない。
D3DPTEXTURECAPS_ALPHA
テクスチャ ピクセルにおいてアルファがサポートされる。
D3DPTEXTURECAPS_SQUAREONLY
テクスチャは、すべて正方形でなければならない。
D3DPTEXTURECAPS_TEXREPEATNOTSCALEDBYSIZE
テクスチャ インデックスは、補間実行前には、テクスチャ サイズに合わせてスケーリングされない。
D3DPTEXTURECAPS_ALPHAPALETTE
デバイスは、テクスチャ パレットからアルファを描画できる。
D3DPTEXTURECAPS_NONPOW2CONDITIONAL
場合によっては、ディメンジョンが 2 の累乗でないテクスチャの使用をサポートする。以下の条件をすべて満たす場合、この能力を公開するデバイスではこのようなテクスチャを使用できる。
  • テクスチャ ステージのテクスチャ アドレッシング モードが、D3DTADDRESS_CLAMP に設定されている。
  • テクスチャ ステージのテクスチャ ラッピングが無効になっている (D3DRS_WRAPn を 0 に設定)。
  • ミップマッピングが使用されていない (拡大フィルタのみを使用)。
D3DPTEXTURECAPS_PROJECTED
D3DTTFF_PROJECTED テクスチャ トランスフォーム フラグをサポートする。この能力が適用されている場合、デバイスはトランスフォーム済みテクスチャ座標を最後のテクスチャ座標で除算する。この能力がサポートされている場合、ピクセル単位に射影除算が行われる。この能力が設定されていない場合に、アプリケーションで射影除算を行う場合は、Direct3D ランタイムによって頂点ごとに実行される。
D3DPTEXTURECAPS_CUBEMAP
キューブ テクスチャをサポートする。
D3DPTEXTURECAPS_VOLUMEMAP
デバイスは、ボリューム テクスチャをサポートする。
D3DPTEXTURECAPS_MIPMAP
デバイスは、ミップマップ化テクスチャをサポートする。
D3DPTEXTURECAPS_MIPVOLUMEMAP
デバイスは、ミップマップ化ボリューム テクスチャをサポートする。
D3DPTEXTURECAPS_MIPCUBEMAP
デバイスは、ミップマップ化キューブ テクスチャをサポートする。
D3DPTEXTURECAPS_CUBEMAP_POW2
デバイスでは、キューブ テクスチャ マップのディメンジョンは 2 の累乗で指定されなければならない。
D3DPTEXTURECAPS_VOLUMEMAP_POW2
デバイスでは、ボリューム テクスチャ マップのディメンジョンは 2 の累乗で指定されなければならない。

注意

これらのフラグは、組み合わせて、D3DCAPS8 の TextureCaps メンバで使用できる。

参照

D3DCAPS8


CONST_D3DPTFILTERCAPSFLAGS

テクスチャのフィルタリング能力を定義する。

Enum CONST_D3DPTFILTERCAPSFLAGS
    D3DPTFILTERCAPS_MINFPOINT         =       256 (&H100)
    D3DPTFILTERCAPS_MINFLINEAR        =       512 (&H200)
    D3DPTFILTERCAPS_MINFANISOTROPIC   =      1024 (&H400)
    D3DPTFILTERCAPS_MIPFPOINT         =     65536 (&H10000)
    D3DPTFILTERCAPS_MIPFLINEAR        =    131072 (&H20000)
    D3DPTFILTERCAPS_MAGFPOINT         =  16777216 (&H1000000)
    D3DPTFILTERCAPS_MAGFLINEAR        =  33554432 (&H2000000)
    D3DPTFILTERCAPS_MAGFANISOTROPIC   =  67108864 (&H4000000)
    D3DPTFILTERCAPS_MAGFAFLATCUBIC    = 134217728 (&H8000000)
    D3DPTFILTERCAPS_MAGFGAUSSIANCUBIC = 268435456 (&H10000000)
End Enum

定数

D3DPTFILTERCAPS_MINFPOINT
デバイスは、ステージ単位に、テクスチャ縮小のためのポイントサンプル フィルタリングをサポートする。ポイント サンプル縮小フィルタは、CONST_D3DTEXTUREFILTERTYPE 列挙のメンバ D3DTEXF_POINT で表される。
D3DPTFILTERCAPS_MINFLINEAR
デバイスは、ステージ単位に、テクスチャ縮小のためのバイリニア補間フィルタリングをサポートする。バイリニア補間縮小フィルタは、CONST_D3DTEXTUREFILTERTYPE 列挙のメンバ D3DTEXF_LINEAR で表される。
D3DPTFILTERCAPS_MINFANISOTROPIC
デバイスは、ステージ単位に、テクスチャ縮小のための異方性フィルタリングをサポートする。異方性縮小フィルタは、CONST_D3DTEXTUREFILTERTYPE 列挙のメンバ D3DTEXF_ANISOTROPIC で表される。
D3DPTFILTERCAPS_MIPFPOINT
デバイスは、ステージ単位に、ミップマップのためのポイント サンプル フィルタリングをサポートする。ポイント サンプル ミップマップ フィルタは、CONST_D3DTEXTUREFILTERTYPE 列挙のメンバ D3DTEXF_POINT で表される。
D3DPTFILTERCAPS_MIPFLINEAR
デバイスは、ステージ単位に、ミップマップのためのトライリニア補間フィルタリングをサポートする。トライリニア補間ミップマップ フィルタは、CONST_D3DTEXTUREFILTERTYPE 列挙のメンバ D3DTEXF_LINEAR で表される。
D3DPTFILTERCAPS_MAGFPOINT
デバイスは、ステージ単位に、テクスチャ拡大のためのポイントサンプル フィルタリングをサポートする。ポイント サンプル拡大フィルタは、CONST_D3DTEXTUREFILTERTYPE 列挙のメンバ D3DTEXF_POINT で表される。
D3DPTFILTERCAPS_MAGFLINEAR
デバイスは、ステージ単位に、テクスチャ拡大のためのバイリニア補間フィルタリングをサポートする。バイリニア補間拡大フィルタは、CONST_D3DTEXTUREFILTERTYPE 列挙のメンバ D3DTEXF_LINEAR で表される。
D3DPTFILTERCAPS_MAGFANISOTROPIC
デバイスは、ステージ単位に、テクスチャ拡大のための異方性フィルタリングをサポートする。異方性拡大フィルタは、CONST_D3DTEXTUREFILTERTYPE 列挙のメンバ D3DTEXF_ANISOTROPIC で表される。
D3DPTFILTERCAPS_MAGFAFLATCUBIC
デバイスは、ステージ単位に、テクスチャ拡大のための平面 3 次 フィルタリングをサポートする。平面 3 次拡大フィルタは、CONST_D3DTEXTUREFILTERTYPE 列挙のメンバ D3DTEXF_FLATCUBIC で表される。
D3DPTFILTERCAPS_MAGFGAUSSIANCUBIC
デバイスは、ステージ単位に、テクスチャ拡大のためのガウス 3 次フィルタリングをサポートする。ガウス 3 次拡大フィルタは、CONST_D3DTEXTUREFILTERTYPE 列挙のメンバ D3DTEXF_GAUSSIANCUBIC で表される。

注意

これらのフラグは、組み合わせて、D3DCAPS8 の TextureFilterCaps メンバで使用できる。

ミップマップ テクスチャに関連する次のフラグは、DirectX 8 ではサポートされていない。

  • D3DPTFILTERCAPS_NEAREST
  • D3DPTFILTERCAPS_LINEAR
  • D3DPTFILTERCAPS_MIPNEAREST
  • D3DPTFILTERCAPS_MIPLINEAR
  • D3DPTFILTERCAPS_LINEARMIPNEAREST
  • D3DPTFILTERCAPS_LINEARMIPLINEAR

参照

D3DCAPS8


CONST_D3DRENDERSTATETYPE

デバイスのレンダリング ステートを定義する。

Enum CONST_D3DRENDERSTATETYPE
    D3DRS_ZENABLE                  =   7
    D3DRS_FILLMODE                 =   8
    D3DRS_SHADEMODE                =   9
    D3DRS_LINEPATTERN              =  10
    D3DRS_ZWRITEENABLE             =  14
    D3DRS_ALPHATESTENABLE          =  15
    D3DRS_LASTPIXEL                =  16 (&H10)
    D3DRS_SRCBLEND                 =  19 (&H13)
    D3DRS_DESTBLEND                =  20 (&H14)
    D3DRS_CULLMODE                 =  22 (&H16)
    D3DRS_ZFUNC                    =  23 (&H17)
    D3DRS_ALPHAREF                 =  24 (&H18)
    D3DRS_ALPHAFUNC                =  25 (&H19)
    D3DRS_DITHERENABLE             =  26 (&H1A)
    D3DRS_ALPHABLENDENABLE         =  27 (&H1B)
    D3DRS_FOGENABLE                =  28 (&H1C)
    D3DRS_SPECULARENABLE           =  29 (&H1D)
    D3DRS_ZVISIBLE                 =  30 (&H1E)
    D3DRS_FOGCOLOR                 =  34 (&H22)
    D3DRS_FOGTABLEMODE             =  35 (&H23)
    D3DRS_FOGSTART                 =  36 (&H24)
    D3DRS_FOGEND                   =  37 (&H25)
    D3DRS_FOGDENSITY               =  38 (&H26)
    D3DRS_EDGEANTIALIAS            =  40 (&H28)
    D3DRS_ZBIAS                    =  47 (&H2F)
    D3DRS_RANGEFOGENABLE           =  48 (&H30)
    D3DRS_STENCILENABLE            =  52 (&H34)
    D3DRS_STENCILFAIL              =  53 (&H35)
    D3DRS_STENCILZFAIL             =  54 (&H36)
    D3DRS_STENCILPASS              =  55 (&H37)
    D3DRS_STENCILFUNC              =  56 (&H38)
    D3DRS_STENCILREF               =  57 (&H39)
    D3DRS_STENCILMASK              =  58 (&H3A)
    D3DRS_STENCILWRITEMASK         =  59 (&H3B)
    D3DRS_TEXTUREFACTOR            =  60 (&H3C)
    D3DRS_WRAP0                    = 128 (&H80)
    D3DRS_WRAP1                    = 129 (&H81)
    D3DRS_WRAP2                    = 130 (&H82)
    D3DRS_WRAP3                    = 131 (&H83)
    D3DRS_WRAP4                    = 132 (&H84)
    D3DRS_WRAP5                    = 133 (&H85)
    D3DRS_WRAP6                    = 134 (&H86)
    D3DRS_WRAP7                    = 135 (&H87)
    D3DRS_CLIPPING                 = 136 (&H88)
    D3DRS_LIGHTING                 = 137 (&H89)
    D3DRS_AMBIENT                  = 139 (&H8B)
    D3DRS_FOGVERTEXMODE            = 140 (&H8C)
    D3DRS_COLORVERTEX              = 141 (&H8D)
    D3DRS_LOCALVIEWER              = 142 (&H8E)
    D3DRS_NORMALIZENORMALS         = 143 (&H8F)
    D3DRS_DIFFUSEMATERIALSOURCE    = 145 (&H91)
    D3DRS_SPECULARMATERIALSOURCE   = 146 (&H92)
    D3DRS_AMBIENTMATERIALSOURCE    = 147 (&H93)
    D3DRS_EMISSIVEMATERIALSOURCE   = 148 (&H94)
    D3DRS_VERTEXBLEND              = 151 (&H97)
    D3DRS_CLIPPLANEENABLE          = 152 (&H98)
    D3DRS_SOFTWAREVERTEXPROCESSING = 153 (&H99)
    D3DRS_POINTSIZE                = 154 (&H9A)
    D3DRS_POINTSIZE_MIN            = 155 (&H9B)
    D3DRS_POINTSPRITEENABLE        = 156 (&H9C)
    D3DRS_POINTSCALEENABLE         = 157 (&H9D)
    D3DRS_POINTSCALE_A             = 158 (&H9E)
    D3DRS_POINTSCALE_B             = 159 (&H9F)
    D3DRS_POINTSCALE_C             = 160 (&HA0)
    D3DRS_MULTISAMPLEANTIALIAS     = 161 (&HA1)
    D3DRS_MULTISAMPLEMASK          = 162 (&HA2)
    D3DRS_PATCHEDGESTYLE           = 163 (&HA3)
    D3DRS_PATCHSEGMENTS            = 164 (&HA4)
    D3DRS_DEBUGMONITORTOKEN        = 165 (&HA5)
    D3DRS_POINTSIZE_MAX            = 166 (&HA6)
    D3DRS_INDEXVERTEXBLENDENABLE   = 167 (&HA7)
    D3DRS_COLORWRITEENABLE         = 168 (&HA8)
    D3DRS_TWEENFACTOR              = 170 (&HAA)
    D3DRS_BLENDOP                  = 171 (&HAB)
End Enum

定数

D3DRS_ZENABLE
CONST_D3DZBUFFERTYPE 列挙のいずれかのメンバで指定する深度バッファ ステート。z バッファリングを有効にするには D3DZB_TRUE、w バッファリングを有効にするには D3DZB_USEW、深度バッファリングを無効にするには D3DZB_FALSE を、それぞれ設定する。

このレンダリング ステートのデフォルト値は、D3DPRESENT_PARAMETERS 構造体の EnableAutoDepthStencil メンバに TRUE を設定してスワップ チェーンと共に深度ステンシルが作成されている場合は D3DZB_TRUE である。そうでない場合は D3DZB_FALSE がデフォルト値になる。

D3DRS_FILLMODE
CONST_D3DFILLMODE 列挙の 1 つ以上のメンバ。デフォルト値は D3DFILL_SOLID である。
D3DRS_SHADEMODE
CONST_D3DSHADEMODE 列挙の 1 つ以上のメンバ。デフォルト値は D3DSHADE_GOURAUD である。
D3DRS_LINEPATTERN
D3DLINEPATTERN 型。デフォルト値は wRepeatPattern が 0 で、wLinePattern が 0 である。
D3DRS_ZWRITEENABLE
アプリケーションによる深度バッファへの書き込みを有効にするには、TRUE を設定する。デフォルト値は TRUE である。アプリケーションはこのメンバを利用することにより、システムが新しい深度値で深度バッファを更新してしまうのを防ぐことができる。FALSE の場合は、レンダリング ステート D3DRS_ZFUNC (深度バッファリングが行われていると仮定) に従って深度比較が実行されるが、深度値はバッファに書き込まれない。
D3DRS_ALPHATESTENABLE
アルファ テストを有効にするには、TRUE を設定する。デフォルト値は FALSE である。このメンバを使用すると、アルファ値に基づいてピクセルを受け取るか拒否するかを判断するテストをオフにできる。

入ってくるアルファ値は、D3DRS_ALPHAFUNC レンダリング ステートにより提供される比較関数を用いて参照アルファ値と比較される。このモードを有効にすると、テストが成功した場合に限りアルファ ブレンディングが行われる。

D3DRS_LASTPIXEL
直線や三角形の最後のピクセルの描画を有効にするには、FALSE を設定する。デフォルト値は TRUE である。
D3DRS_SRCBLEND
CONST_D3DBLEND 列挙のいずれかのメンバ。デフォルト値は D3DBLEND_ONE である。
D3DRS_DESTBLEND
CONST_D3DBLEND 列挙のいずれかのメンバ。デフォルト値は D3DBLEND_ZERO である。
D3DRS_CULLMODE
背面の三角形をカリングする場合に、その方法を指定する。CONST_D3DCULL 列挙型のメンバのいずれかを設定できる。デフォルト値は D3DCULL_CCW である。
D3DRS_ZFUNC
CONST_D3DCMPFUNC 列挙のいずれかのメンバ。デフォルト値は D3DCMP_LESSEQUAL である。このメンバは、アプリケーションにカメラからの距離を基準とするピクセルの受け取りや受け取り拒否を許可する。

ピクセルの深度値を深度バッファの値と比較する。ピクセルの深度値が比較関数で許可された場合、ピクセルが書き込まれる。

深度値が深度バッファに書き込まれるのは、レンダリング ステートが TRUE の場合だけである。

この深度テストに失敗した方が、ソフトウェアによるラスタ化や多くのハードウェア アクセラレータの処理は速くなる。これは、ピクセルのレンダリング処理を行わない場合には、テクスチャをフィルタ処理したり乗算したりする必要がなくなるためである。

D3DRS_ALPHAREF
アルファ テストが有効に設定されている場合に、ピクセルをテストするための基準アルファ値を指定する値。0 から 1 の範囲の 16:16 固定小数点値を指定できる (1.0 は &H00010000 と表される)。デフォルト値は 0.0 である。
D3DRS_ALPHAFUNC
CONST_D3DCMPFUNC 列挙のいずれかのメンバ。デフォルト値は D3DCMP_ALWAYS である。このメンバは、アプリケーションにアルファ値を基準とするピクセルの受け取りや受け取り拒否を許可する。
D3DRS_DITHERENABLE
ディザリングを有効にするには、TRUE を設定する。デフォルト値は FALSE である。
D3DRS_ALPHABLENDENABLE
アルファ ブレンドによる透明化を有効にするには、TRUE を設定する。デフォルト値は FALSE である。

アルファ ブレンディングのタイプは、D3DRS_SRCBLEND と D3DRS_DESTBLEND のレンダリング ステートによって決定される。

D3DRS_FOGENABLE
フォグ ブレンディングを有効にするには、TRUE を設定する。デフォルト値は FALSE である。
D3DRS_SPECULARENABLE
スペキュラ ハイライトを有効にするには、TRUE を設定する。デフォルト値は FALSE である。

スペキュラ ハイライトは、光の当たっているオブジェクトの各頂点がそのオブジェクトの原点にあるかのように算出される。これによって、オブジェクトが原点の周囲でモデル化され、光源とオブジェクト間の距離が比較的大きい場合に限り、結果を予測することができる。

このメンバに TRUE を設定すると、テクスチャ カスケード後、アルファ ブレンディング前に、ベース カラーにスペキュラ色が追加される。

D3DRS_ZVISIBLE
サポートされていない。
D3DRS_FOGCOLOR
RGB 色を示す Long 型の値。デフォルト値は 0 である。
D3DRS_FOGTABLEMODE
ピクセル フォグに使用されるフォグ式。CONST_D3DFOGMODE 列挙のいずれかのメンバを設定する。デフォルト値は D3DFOG_NONE である。
D3DRS_FOGSTART
線形フォグ モードで、ピクセルまたは頂点フォグ エフェクトが開始する深度。深度は、頂点フォグの場合はワールド空間で、ピクセル フォグの場合はデバイス空間 [0.0, 1.0] またはワールド空間のいずれかで指定する。ピクセル フォグでは、フォグ計算に Z が使用される場合、これらの値はデバイス空間にあり、視点との相対フォグ (W フォグ) が使用される場合はワールド空間にある。
D3DRS_FOGEND
線形フォグ モードで、ピクセルまたは頂点フォグ エフェクトが終了する深度。深度は、頂点フォグの場合はワールド空間で、ピクセル フォグの場合はデバイス空間 [0.0, 1.0] またはワールド空間のいずれかで指定する。ピクセル フォグでは、フォグ計算に Z が使用される場合、これらの値はデバイス空間にあり、視点との相対フォグ (W フォグ) が使用される場合はワールド空間にある。
D3DRS_FOGDENSITY
指数フォグ モード (D3DFOG_EXP および D3DFOG_EXP2) で使用するピクセルまたは頂点フォグのフォグ密度。密度の有効な値は 0.0 から 1.0 の範囲内である。デフォルト値は 1.0 である。
D3DRS_EDGEANTIALIAS
オブジェクトの凸面の輪郭を形成する線をアンチエイリアスするには、TRUE を設定する。デフォルト値は FALSE である。TRUE の場合、アプリケーションでは、直線のみレンダリングし、またシーン内のポリゴンの外辺に対してのみレンダリングすることが望ましい。このレンダリング ステートが設定されていて、三角形またはポイントが描画されると、その動作は不定である。アンチエイリアシングは、隣接ピクセルの値の平均値をとることによって実行される。この方法は、アンチエイリアシングの実行方法としてこれは最善ではないが、効率的ではある。この種の処理をサポートするハードウェアは普及しつつある。

エッジ アンチエイリアシングは、D3DPRASTERCAPS_ANTIALIASEDGES 能力を公開するデバイスに限り、有効にすることができる。

D3DRS_ZBIAS
0 ～ 16 の範囲の整数値であり、物理的に同一の面にあるポリゴンを分離して見えるようにする。描画順序のソーティングを行わなくても、高い Z バイアス値を持つポリゴンは、低い値を持つポリゴンよりも手前に見える。たとえば、値が 1 のポリゴンは、値が 0 のポリゴンより手前に見える。デフォルト値は 0 である。
D3DRS_RANGEFOGENABLE
範囲ベースの頂点フォグを有効にするには、TRUE を設定する。デフォルト値は FALSE で、システムは深度ベースのフォグを使用する。範囲ベースのフォグでは、シーンにおけるオブジェクトの深度 (z 座標) ではなく、ビューアからのオブジェクトの距離でフォグ エフェクトを計算する。範囲ベースのフォグでは、通常のすべてのフォグ メソッドが機能するが、深度ではなく範囲を使って計算を行うポイントだけが異なる。

範囲はフォグ計算に使用する適切な要素であるが、範囲は計算のポイントで負荷が高く、深度は通常計算済みなので、代わりに深度が広く使われる。深度を使用してフォグを計算すると、周辺オブジェクトのフォグ エフェクトが視点の移動と共に変化するという好ましくない影響が出る。この場合、深度は変化するが範囲は一定のままである。

現在のところ、ピクセル単位の範囲ベースのフォグをサポートするハードウェアは存在しないため、範囲補正は頂点フォグでのみ行われる。

D3DRS_STENCILENABLE
ステンシル処理を有効にするには TRUE を設定し、ステンシル処理を無効にするには FALSE を設定する。デフォルト値は FALSE である。
D3DRS_STENCILFAIL
ステンシル テストに失敗したときに実行するステンシル処理。CONST_D3DSTENCILOP 列挙のいずれかのメンバを指定できる。デフォルト値は D3DSTENCILOP_KEEP である。
D3DRS_STENCILZFAIL
ステンシル テストにパスし、深度テスト (Z テスト) に失敗した場合に実行するステンシル処理。CONST_D3DSTENCILOP 列挙のいずれかのメンバを指定できる。デフォルト値は D3DSTENCILOP_KEEP である。
D3DRS_STENCILPASS
ステンシル テストおよび深度 (Z) テストの両方にパスした場合に実行するステンシル処理。CONST_D3DSTENCILOP 列挙のいずれかのメンバを指定できる。デフォルト値は D3DSTENCILOP_KEEP である。
D3DRS_STENCILFUNC
ステンシル テストのための比較関数。CONST_D3DCMPFUNC 列挙のいずれかのメンバを指定できる。デフォルト値は D3DCMP_ALWAYS である。

比較関数は、ステンシル バッファの要素を基準値と比較するために使われる。この比較は、基準値のビット、およびステンシル マスク (D3DRS_STENCILMASK レンダリング ステートにより設定) に設定されたステンシル バッファ要素にのみ適用される。TRUE の場合、ステンシル テストは成功である。

D3DRS_STENCILREF
ステンシル テストのための基準整数値。デフォルト値は 0 である。
D3DRS_STENCILMASK
基準値および各ステンシル バッファ要素に適用し、ステンシル テストのための有効ビットを決定するマスク。デフォルトのマスクは &HFFFFFFFF である。
D3DRS_STENCILWRITEMASK
基準値および各ステンシル バッファ要素に適用し、ステンシル テストのための有効ビットを決定するマスク。デフォルトのマスクは &HFFFFFFFF である。
D3DRS_TEXTUREFACTOR
D3DTA_TFACTOR テクスチャ ブレンディング引数または D3DTOP_BLENDFACTORALPHA テクスチャ ブレンディング処理によるマルチテクスチャ ブレンディングで使用される色。
D3DRS_WRAP0 ～ D3DRS_WRAP7
複数のテクスチャ座標セットに対するテクスチャ ラッピング動作。これらのレンダリング ステートの有効値としては、CONST_D3DWRAPFLAGS 列挙で定義されている D3DWRAPCOORD_0 (または D3DWRAP_U)、D3DWRAPCOORD_1 (または D3DWRAP_V)、D3DWRAPCOORD_2 (または D3DWRAP_W)、および D3DWRAPCOORD_3 の各フラグの任意の組み合わせを指定できる。これらの値を設定すると、指定されたテクスチャに対して第一、第二、第三、第四ディメンジョンの方向 (s、ｔ、ｒ、および q 方向と呼ばれる場合もある) のラッピングが実行される。デフォルト値は 0 (すべての方向でラッピング無効) である。
D3DRS_CLIPPING
Microsoft® Direct3D® によるプリミティブのクリッピングを有効にするには TRUE、無効にするには FALSE を設定する。デフォルト値は TRUE である。
D3DRS_LIGHTING
Direct3D のライティングを有効にするには TRUE、無効にするには FALSE を設定する。デフォルト値は TRUE である。頂点法線を含む頂点のみ正しくライトが当てられ、法線を含まない頂点ではすべてのライティング計算で 0 の内積が使用される。
D3DRS_AMBIENT
アンビエント ライトの色。デフォルト値は 0 である。
D3DRS_FOGVERTEXMODE
頂点フォグで使われるフォグ式。CONST_D3DFOGMODE 列挙のいずれかのメンバに設定する。デフォルト値は D3DFOG_NONE である。このレンダリング ステートは、従来の D3DLIGHTSTATE_FOGVERTEXMODE ライティング ステートに類似する。
D3DRS_COLORVERTEX
頂点単位のカラーを有効にするには TRUE、無効にするには FALSE を設定する。デフォルト値は TRUE である。頂点単位のカラーを有効にすると、各頂点に定義された色をライティング計算で使用することができる。

詳細については、以下のレンダリング ステートを参照すること。

  • D3DRS_DIFFUSEMATERIALSOURCE
  • D3DRS_SPECULARMATERIALSOURCE
  • D3DRS_AMBIENTMATERIALSOURCE
  • D3DRS_EMISSIVEMATERIALSOURCE
D3DRS_LOCALVIEWER
カメラとの相対角度に依存したスペキュラ ハイライトを有効にするには TRUE を設定し、正スペキュラ ハイライトを使用するには FALSE を設定する。デフォルト値は TRUE である。正射影を使用するアプリケーションでは FALSE を指定すること。
D3DRS_NORMALIZENORMALS
頂点法線の自動正規化を有効にするには TRUE、無効にするには FALSE を設定する。デフォルト値は FALSE である。この機能を有効にすると、頂点がカメラ空間にトランスフォームされた後で頂点法線が正規化されるが、計算負荷が大きい。
D3DRS_DIFFUSEMATERIALSOURCE
ライティング計算に使用されるディフューズ色のソース。有効な値は、CONST_D3DMATERIALCOLORSOURCE 列挙のメンバである。デフォルト値は D3DMCS_COLOR1 である。このレンダリング ステートの値が使用されるのは、D3DRS_COLORVERTEX レンダリング ステートが TRUE に設定されている場合だけである。
D3DRS_SPECULARMATERIALSOURCE
ライティング計算に使用されるスペキュラ色のソース。有効値は CONST_D3DMATERIALCOLORSOURCE 列挙のメンバである。デフォルト値は D3DMCS_COLOR2 である。
D3DRS_AMBIENTMATERIALSOURCE
ライティング計算に使用されるアンビエント色のソース。有効値は CONST_D3DMATERIALCOLORSOURCE 列挙のメンバである。デフォルト値は D3DMCS_COLOR2 である。
D3DRS_EMISSIVEMATERIALSOURCE
ライティング計算に使用されるエミッション色のソース。有効値は CONST_D3DMATERIALCOLORSOURCE 列挙のメンバである。デフォルト値は D3DMCS_MATERIAL である。
D3DRS_VERTEXBLEND
ジオメトリがある場合、ジオメトリ ブレンディングを実行するために使用する行列の個数。有効な値は、CONST_D3DVERTEXBLENDFLAGS 列挙のメンバ。デフォルト値は D3DVBF_DISABLE である。
D3DRS_CLIPPLANEENABLE
ユーザー定義のクリップ面を有効または無効にする。有効な値は、CONST_D3DCLIPPLANEFLAGS 列挙の値の組み合わせ。列挙の値を指定すると、対応するクリップ面が有効になる。値を指定しないと、クリップ面は無効になる。デフォルト値は D3DCPF_DISABLEALL である。
D3DRS_SOFTWAREVERTEXPROCESSING
ハードウェア頂点処理またはソフトウェア頂点処理の設定をアプリケーションから照会および選択できるようにする値。デバイスの種類が D3DDEVTYPE_SW の場合、この値は TRUE の固定である。デバイスの種類が D3DDEVTYPE_REF の場合は、アプリケーションでこの値を設定できる。デバイスの種類が D3DDEVTYPE_HAL の場合は、D3DDEVCAPS_HWTRANSFORMANDLIGHT が設定されているときに限り、アプリケーションでこの値を設定できる。それ以外の場合、このフラグは TRUE に固定される。可変の場合、デフォルト値は FALSE である。

両方の頂点処理が可能なモードにおいて、頂点処理のレンダリング ステートを変更すると、カレント ストリーム、インデックス、および頂点シェーダは、デフォルト値の ByVal 0 または 0 にリセットされる。

D3DRS_POINTSIZE
各頂点に対してポイント サイズが指定されていない場合に、ポイント サイズ計算で使用するサイズを指定する値。頂点がポイント サイズを含んでいる場合、この値は使用されない。この値は、D3DRS_POINTSCALEENABLE が FALSE の場合はスクリーン空間単位で指定する。それ以外の場合は、ワールド空間単位で指定する。デフォルト値は 1.0 である。この値の範囲は、0.0 以上である。
D3DRS_POINTSIZE_MIN
ポイント プリミティブの最小サイズを指定する値。レンダリングの間、ポイント プリミティブはこのサイズに固定される。1.0 より小さい値を設定すると、ポイントにピクセルの中心が含まれずにアンチエイリアシングが無効になっている場合はポイントが表示されなくなり、アンチエイリアシングが有効になっている場合は低い輝度でレンダリングされる。デフォルト値は 1.0 である。この値の範囲は、0.0 以上である。
D3DRS_POINTSPRITEENABLE
TRUE の場合は、テクスチャ全体が各ポイントにマッピングされるようにポイント プリミティブのテクスチャ座標が設定される。FALSE の場合は、頂点のテクスチャ座標がポイント全体に対して使用される。デフォルト値は FALSE である。D3DRS_POINTSCALEENABLE に FALSE (デフォルト値) を設定し、D3DRS_POINTSIZE に 1.0 (デフォルト値) を設定することで、DirectX 7 スタイルのシングルピクセル ポイントを実現できる。
D3DRS_POINTSCALEENABLE
ポイント プリミティブに対するサイズの計算を制御する値。TRUE の場合、ポイント サイズはカメラ空間の値として解釈され、距離関数および視錐台によってビューポートの Y 軸のスケーリングになるように調整されて、最終的なスクリーン空間のポイント サイズが計算される。FALSE の場合、ポイント サイズはスクリーン空間の値と解釈されて、そのまま使われる。デフォルト値は FALSE である。
D3DRS_POINTSCALE_A
ポイント プリミティブに対する距離ベースのサイズの減衰を制御する浮動小数点値。D3DRS_POINTSCALEENABLE が TRUE の場合にのみ有効である。デフォルト値は 1.0 である。この値の範囲は、0.0 以上である。
D3DRS_POINTSCALE_B
ポイント プリミティブに対する距離ベースのサイズの減衰を制御する浮動小数点値。D3DRS_POINTSCALEENABLE が TRUE の場合にのみ有効である。デフォルト値は 0.0 である。この値の範囲は、0.0 以上である。
D3DRS_POINTSCALE_C
ポイント プリミティブに対する距離ベースのサイズの減衰を制御する浮動小数点値。D3DRS_POINTSCALEENABLE が TRUE の場合にのみ有効である。デフォルト値は 0.0 である。この値の範囲は、0.0 以上である。
D3DRS_MULTISAMPLEANTIALIAS
マルチサンプル レンダリングのターゲット バッファを使うときの、個々のサンプルの計算方法を決定する値。TRUE の場合は、複数サンプルのそれぞれについて異なるサンプリング位置でサンプリングすることでフルシーン アンチエイリアシングを実行するように、複数のサンプルが計算される。FALSE の場合は、複数のサンプルはすべて同じサンプリング値 (ピクセルの中心でサンプリングされた値) で記述されて、マルチサンプル バッファに対する非アンチエイリアシング レンダリングが可能になる。シングル サンプル バッファへのレンダリング時、このレンダリング ステートはエフェクトを持たない。デフォルト値は TRUE である。
D3DRS_MULTISAMPLEMASK
LSB を先頭とするこのマスクの各ビットは、マルチサンプル レンダリング ターゲットの 1 つのサンプルに対する変更を制御する。したがって、8 サンプルのレンダリング ターゲットの場合は、8 つのサンプルのそれぞれに対する 8 つの書き込み許可情報が、下位バイトに格納されている。シングル サンプル バッファへのレンダリング時、このレンダリング ステートはエフェクトを持たない。デフォルト値は &HFFFFFFFF である。

このレンダリング ステートを使うと、マルチサンプル バッファを蓄積バッファとして使い、各パスがサンプルのサブセットを更新するようなジオメトリのマルチパス レンダリングを行うことができる。

D3DRS_PATCHEDGESTYLE
パッチのエッジでフロート型のテッセレーションを使用するかどうかを設定する。使用できる値は、CONST_D3DPATCHEDGESTYLE 列挙型によって定義される。
D3DRS_PATCHSEGMENTS
高次プリミティブを描画するときのエッジごとのセグメントの数。
D3DRS_DEBUGMONITORTOKEN
モニタをデバッグする場合にのみ設定する。
D3DRS_POINTSIZE_MAX
ポイント スプライトが制限される最大サイズを指定する値。値は、D3DCAPS8 の MaxPointSize メンバ以下で、D3DRS_POINTSIZE_MIN 以上でなければならない。
D3DRS_INDEXVERTEXBLENDENABLE
TRUE の場合は、インデックス付き頂点ブレンディングが有効である。FALSE の場合、インデックス付き頂点ブレンディングが無効である。このレンダリング ステートが有効な場合は、頂点ごとにパックされた LONG で行列インデックスを渡さなければならない。このレンダリング ステートを無効にし、D3DRS_VERTEXBLEND ステートを使って頂点ブレンディングを有効にすることは、すべての頂点について行列インデックス 0、1、2、3 を指定することと同じである。
D3DRS_COLORWRITEENABLE
レンダリング ターゲットのカラー バッファに対するチャネルごとの書き込みを有効にする値。ビットを設定すると、3D レンダリングの間にカラー チャネルが更新される。ビットをクリアすると、カラー チャネルは更新されない。デバイスに対して D3DCAPS8 型の PrimitiveMiscCaps メンバに D3DPMISCCAPS_COLORWRITEENABLE 能力ビットが設定されている場合、この機能は有効である。このレンダリング ステートは、クリア処理に影響を与えない。デフォルト値は &H0000000F である。

このレンダリング ステートの有効値は、CONST_D3DCOLORWRITEENABLEFLAGS 列挙で定義されている値の任意の組み合わせである。

D3DRS_TWEENFACTOR
トゥイーン係数を制御する値。
D3DRS_BLENDOP
アルファ ブレンディング レンダリング ステートの D3DRS_ALPHABLENDENABLE が TRUE に設定されている場合に適用する算術処理の選択に使用される値。有効な値は、CONST_D3DBLENDOP 列挙型で定義される。デフォルト値は D3DBLENDOP_ADD である。

D3DPMISCCAPS_BLENDOP デバイス能力がサポートされていない場合は、D3DBLENDOP_ADD が実行される。

注意

Direct3D は、アプリケーションでの便宜を考慮して、(D3DRS_WRAPn ステート値の 1 つを明示的に使用する代わりに) CONST_D3DWRAPBIAS 列挙で定義されている定数 D3DRENDERSTATE_WRAPBIAS を定義し、テクスチャ座標セットのゼロから始まる整数値に基づいて、テクスチャ ラッピングを有効にしたり、無効にしたりする。次の例のように、D3DRENDERSTATE_WRAPBIAS 値をテクスチャ座標セットのゼロ始点インデックスに加算して、そのインデックスに対応する D3DRS_WRAPn 値を計算する。

    On Local Error Resume Next

    ' 変数 lIndex のインデックスに対応するテクスチャ座標セットを
    ' 使用するテクスチャに対して、U/V ラッピングを有効にする。
    Call d3dDevice8.SetRenderState( _
            lIndex + D3DRENDERSTATE_WRAPBIAS, _
            D3DWRAPCOORD_0 Or D3DWRAPCOORD_1)

    ' lIndexが 3 の場合、加算の結果の値は、
    ' D3DRENDERSTATE_WRAP3 (131) に等しくなる。
    If Err.Number <> DD_OK Then
       ' エラー処理コード。
    End If


CONST_D3DRESOURCETYPE

リソースの種類を定義する。

Enum CONST_D3DRESOURCETYPE
    D3DRTYPE_SURFACE       = 1
    D3DRTYPE_VOLUME        = 2
    D3DRTYPE_TEXTURE       = 3
    D3DRTYPE_VOLUMETEXTURE = 4
    D3DRTYPE_CUBETEXTURE   = 5
    D3DRTYPE_VERTEXBUFFER  = 6
    D3DRTYPE_INDEXBUFFER   = 7
End Enum

定数

D3DRTYPE_SURFACE
サーフェス リソース。
D3DRTYPE_VOLUME
ボリューム リソース。
D3DRTYPE_TEXTURE
テクスチャ リソース。
D3DRTYPE_VOLUMETEXTURE
ボリューム テクスチャ リソース。
D3DRTYPE_CUBETEXTURE
キューブ テクスチャ リソース。
D3DRTYPE_VERTEXBUFFER
頂点バッファ リソース。
D3DRTYPE_INDEXBUFFER
インデックス バッファ リソース。

参照

Direct3DResource8.GetType


CONST_D3DSCPFLAGS

カーソルの更新オプションを定義する。

Enum CONST_D3DSCPFLAGS
     D3DCURSOR_IMMEDIATE_UPDATE = 1
End Enum

定数

D3DCURSOR_IMMEDIATE_UPDATE
リフレッシュ レートでカーソルを更新する。

参照

Direct3DDevice8.SetCursorPosition


CONST_D3DSGRFLAGS

ガンマ修正を適用するかどうかを示す定数を定義する。

Enum CONST_D3DSGRFLAGS
    D3DSGR_NO_CALIBRATION = 0
    D3DSGR_CALIBRATE      = 1
End Enum

定数

D3DSGR_NO_CALIBRATION
ガンマ修正を適用しない。提供されているガンマ テーブルが、デバイスに直接転送される。
D3DSGR_CALIBRATE
ガンマ口径測定器がインストールされている場合は、システムおよびモニタの応答カーブに合わせて、デバイスに送信される前にランプが調整される。

口径測定器がインストールされていない場合は、ランプはデバイスに直接渡される。

参照

Direct3DDevice8.SetGammaRamp


CONST_D3DSHADEMODE

サポートされているシェーディング モードを示す定数を定義する。

Enum CONST_D3DSHADEMODE
    D3DSHADE_FLAT    = 1
    D3DSHADE_GOURAUD = 2
    D3DSHADE_PHONG   = 3
End Enum

定数

D3DSHADE_FLAT
フラット シェーディング モード。三角形の最初の頂点の色成分とスペキュラ成分が、表面の色成分とスペキュラ成分を決定するために使われる。この色は三角形全体にわたってむらなく適用される。つまり、補間されない。スペキュラ アルファは補間される。「注意」を参照すること。
D3DSHADE_GOURAUD
グーロー シェーディング モード。表面の色成分とスペキュラ成分は、三角形の 3 つの頂点間の線形補間により決定される。
D3DSHADE_PHONG
フォン シェーディング モード。このモードは、現在サポートされていない。

注意

フラット シェーディング モードの三角形の最初の頂点は、次のように定義される。

  • 三角形リストの場合、三角形 i の最初の頂点は i * 3 である。
  • 三角形ストリップの場合、三角形 i の最初の頂点は頂点 i である。
  • 三角形ファンの場合、三角形 i の最初の頂点は頂点 i + 1 である。

これらのフラグは、CONST_D3DRENDERSTATETYPE 列挙の D3DRS_SHADEMODE レンダリング ステートの値を設定するために使われる。

参照

CONST_D3DRENDERSTATETYPE


CONST_D3DSPDFLAGS

プライベート データの管理方法を定義する。

Enum CONST_D3DSPDFLAGS
    D3DSPD_IUNKNOWN = 1
End Enum

定数

D3DSPD_IUNKNOWN
渡されたデータが必要なくなっている場合、Microsoft® Direct3D® はそのデータに関連付けられているメモリを自動的に解放する。

参照

Direct3DResource8.SetPrivateData、Direct3DSurface8.SetPrivateData、Direct3DVolume8.SetPrivateData


CONST_D3DSTATEBLOCKTYPE

デバイス ステートの論理グループを定義する。

Enum CONST_D3DSTATEBLOCKTYPE
    D3DSBT_ALL         = 1
    D3DSBT_PIXELSTATE  = 2
    D3DSBT_VERTEXSTATE = 3
End Enum

定数

D3DSBT_ALL
すべてのデバイス ステートを取り込む。
現在のすべてのレンダリング ステート | 現在のすべてのクリップ面
現在のすべてのテクスチャ ステージ ステート | 現在のマテリアル
現在のすべてのテクスチャ | 現在のすべてのライトおよび有効なライト パラメータ
現在のパレット | 現在のピクセル シェーダ
現在のすべてのストリーム | 現在のピクセル シェーダ定数
現在のビューポート | 現在の頂点シェーダ
現在のすべてのトランスフォーム | 現在の頂点シェーダ定数

D3DSBT_PIXELSTATE
次のすべてのピクセル関連デバイス ステートを取り込む。

レンダリング ステート
D3DRS_ALPHABLENDENABLE D3DRS_ALPHAFUNC
D3DRS_ALPHAREF D3DRS_ALPHATESTENABLE
D3DRS_BLENDOP D3DRS_COLORWRITEENABLE
D3DRS_DESTBLEND D3DRS_DITHERENABLE
D3DRS_EDGEANTIALIAS D3DRS_FILLMODE
D3DRS_FOGDENSITY D3DRS_FOGEND
D3DRS_FOGSTART D3DRS_LASTPIXEL
D3DRS_LINEPATTERN D3DRS_SHADEMODE
D3DRS_SRCBLEND D3DRS_STENCILENABLE
D3DRS_STENCILFAIL D3DRS_STENCILFUNC
D3DRS_STENCILMASK D3DRS_STENCILPASS
D3DRS_STENCILREF D3DRS_STENCILWRITEMASK
D3DRS_STENCILZFAIL D3DRS_TEXTUREFACTOR
D3DRS_WRAP0 through D3DRS_WRAP7 D3DRS_ZBIAS
D3DRS_ZENABLE D3DRS_ZFUNC
D3DRS_ZWRITEENABLE

テクスチャ ステージ ステート
D3DTSS_ADDRESSU D3DTSS_ADDRESSV
D3DTSS_ADDRESSW D3DTSS_ALPHAARG0
D3DTSS_ALPHAARG1 D3DTSS_ALPHAARG2
D3DTSS_ALPHAOP D3DTSS_BORDERCOLOR
D3DTSS_BUMPENVLOFFSET D3DTSS_BUMPENVLSCALE
D3DTSS_BUMPENVMAT00 D3DTSS_BUMPENVMAT01
D3DTSS_BUMPENVMAT10 D3DTSS_BUMPENVMAT11
D3DTSS_COLORARG0 D3DTSS_COLORARG1
D3DTSS_COLORARG2 D3DTSS_COLOROP
D3DTSS_MAGFILTER D3DTSS_MAXANISOTROPY
D3DTSS_MAXMIPLEVEL D3DTSS_MINFILTER
D3DTSS_MIPFILTER D3DTSS_MIPMAPLODBIAS
D3DTSS_RESULTARG D3DTSS_TEXCOORDINDEX
D3DTSS_TEXTURETRANSFORMFLAGS

D3DSBT_VERTEXSTATE
現在のすべてのライト、現在の頂点シェーダと頂点シェーダ定数、および D3DTSS_TEXCOORDINDEX と D3DTSS_TEXTURETRANSFORMFLAGS で指定されるテクスチャ ステージ ステートを取り込む。また、D3DSBT_VERTEXSTATE は、次のすべての頂点関連デバイス ステートを取り込む。

レンダリング ステート
D3DRS_AMBIENT D3DRS_AMBIENTMATERIALSOURCE
D3DRS_CLIPPING D3DRS_CLIPPLANEENABLE
D3DRS_COLORVERTEX D3DRS_DIFFUSEMATERIALSOURCE
D3DRS_EMISSIVEMATERIALSOURCE D3DRS_FOGDENSITY
D3DRS_FOGEND D3DRS_FOGSTART
D3DRS_FOGTABLEMODE D3DRS_FOGVERTEXMODE
D3DRS_INDEXVERTEXBLENDENABLE D3DRS_LIGHTING
D3DRS_LOCALVIEWER D3DRS_MULTISAMPLEANTIALIAS
D3DRS_MULTISAMPLEMASK D3DRS_NORMALIZENORMALS
D3DRS_PATCHEDGESTYLE D3DRS_PATCHSEGMENTS
D3DRS_POINTSCALE_A D3DRS_POINTSCALE_B
D3DRS_POINTSCALE_C D3DRS_POINTSCALEENABLE
D3DRS_POINTSIZE D3DRS_POINTSIZE_MAX
D3DRS_POINTSIZE_MIN D3DRS_POINTSPRITEENABLE
D3DRS_RANGEFOGENABLE D3DRS_SOFTWAREVERTEXPROCESSING
D3DRS_SPECULARMATERIALSOURCE D3DRS_TWEENFACTOR
D3DRS_VERTEXBLEND

注意

D3DSBT_PIXELSTATE と D3DSBT_VERTEXSTATE はデバイス ステートの異なる論理グループを示しているが、ステートによっては両方のグループに共通するものもある。D3DSBT_PIXELSTATE および D3DSBT_VERTEXSTATE の組み合わせは D3DSBT_ALL と同等ではない。D3DSBT_PIXELSTATE および D3DSBT_VERTEXSTATE 値を使用することで、Direct3Ddevice8.DrawPrimitive の呼び出しの間に頻繁に変更されるステートを取り込むことができ、ステート全体を取り込むことによるパフォーマンスへの悪影響はない。

参照

Direct3DDevice8.CreateStateBlock


CONST_D3DSTENCILCAPFLAGS

ステンシル バッファ能力フラグを定義する。

Enum CONST_D3DSTENCILCAPFLAGS
    D3DSTENCILCAPS_KEEP    =   1
    D3DSTENCILCAPS_ZERO    =   2
    D3DSTENCILCAPS_REPLACE =   4
    D3DSTENCILCAPS_INCRSAT =   8
    D3DSTENCILCAPS_DECRSAT =  16 (&H10)
    D3DSTENCILCAPS_INVERT  =  32 (&H20)
    D3DSTENCILCAPS_INCR    =  64 (&H40)
    D3DSTENCILCAPS_DECR    = 128 (&H80)
End Enum

定数

D3DSTENCILCAPS_KEEP
D3DSTENCILOP_KEEP 処理をサポートする。
D3DSTENCILCAPS_ZERO
D3DSTENCILOP_ZERO 処理をサポートする。
D3DSTENCILCAPS_REPLACE
D3DSTENCILOP_REPLACE 処理をサポートする。
D3DSTENCILCAPS_INCRSAT
D3DSTENCILOP_INCRSAT 処理をサポートする。
D3DSTENCILCAPS_DECRSAT
D3DSTENCILOP_DECRSAT 処理をサポートする。
D3DSTENCILCAPS_INVERT
D3DSTENCILOP_INVERT 処理をサポートする。
D3DSTENCILCAPS_INCR
D3DSTENCILOP_INCR 処理をサポートする。
D3DSTENCILCAPS_DECR
D3DSTENCILOP_DECR 処理をサポートする。

注意

これらのフラグは、組み合わせて、D3DCAPS8 の StencilCaps メンバで使用できる。

ステンシル処理の定義については、CONST_D3DSTENCILOP を参照すること。

参照

D3DCAPS8、CONST_D3DSTENCILOP


CONST_D3DSTENCILOP

ステンシル処理を規定する定数を定義する。

Enum CONST_D3DSTENCILOP
    D3DSTENCILOP_KEEP    = 1
    D3DSTENCILOP_ZERO    = 2
    D3DSTENCILOP_REPLACE = 3
    D3DSTENCILOP_INCRSAT = 4
    D3DSTENCILOP_DECRSAT = 5
    D3DSTENCILOP_INVERT  = 6
    D3DSTENCILOP_INCR    = 7
    D3DSTENCILOP_DECR    = 8
End Enum

定数

D3DSTENCILOP_KEEP
ステンシル バッファ内の項目を更新しない。デフォルト値。
D3DSTENCILOP_ZERO
ステンシル バッファ内の項目をゼロに設定する。
D3DSTENCILOP_REPLACE
ステンシル バッファ内の項目を基準値で置き換える。
D3DSTENCILOP_INCRSAT
ステンシル バッファ内の項目の値を、最大値に達するまで増加させる。ステンシル バッファの最大値については、「注意」を参照すること。
D3DSTENCILOP_DECRSAT
ステンシル バッファ内の項目の値を 0 になるまで減少させる。
D3DSTENCILOP_INVERT
ステンシル バッファ内の項目のビットを反転する。
D3DSTENCILOP_INCR
ステンシル バッファ内の項目の値を増加させ、最大値を超えた場合はラッピングしてゼロに戻す。ステンシル バッファの最大値については、「注意」を参照すること。
D3DSTENCILOP_DECR
ステンシル バッファ内の項目の値を減少させ、新しい値が 0 より小さくなった場合は最大値に戻す。

注意

ステンシル バッファ項目は 0 から 2n -1 までの範囲の整数値を取る。n はステンシル バッファのビット深度である。

これらのフラグは、CONST_D3DRENDERSTATETYPE 列挙の D3DRS_STENCILFAIL、D3DRS_STENCILZFAIL、および D3DRS_STENCILPASS の各レンダリング ステートの値を設定するために使われる。

参照

CONST_D3DRENDERSTATETYPE


CONST_D3DSWAPEFFECT

スワップ エフェクトを定義する。

Enum CONST_D3DSWAPEFFECT
    D3DSWAPEFFECT_DISCARD    = 1
    D3DSWAPEFFECT_FLIP       = 2
    D3DSWAPEFFECT_COPY       = 3
    D3DSWAPEFFECT_COPY_VSYNC = 4
End Enum

定数

D3DSWAPEFFECT_DISCARD
スワップ エフェクトの D3DSWAPEFFECT_FLIP、D3DSWAPEFFECT_COPY、または D3DSWAPEFFECT_COPY_VSYNC を使用してスワップ チェーンを作成した場合、ランタイムは Direct3DDevice8.Present 処理がバック バッファの内容に影響しないことを保証する。ただし、特にウィンドウ スワップ チェーンのフリップ セマンティクスや、フルスクリーン スワップ チェーンのコピー セマンティスクを実装する際には、この保証を満たすためにかなりのビデオ メモリのオーバーヘッドや処理のオーバーヘッドが伴うことがある。アプリケーションでは D3DSWAPEFFECT_DISCARD スワップ エフェクトを使うことで、これらのオーバーヘッドを回避することができ、最も効率的なスワップ チェーンの表現方法をディスプレイ ドライバ側で選択できる。また、これは、D3DPRESENT_PARAMETERS の MultiSampleType メンバに D3DMULTISAMPLE_NONE 以外の値を指定した際に使用できる唯一のスワップ エフェクトである。

D3DSWAPEFFECT_FLIP を使用するスワップ チェーンと同様、D3DSWAPEFFECT_DISCARD を使用するスワップ チェーンは複数のバック バッファを含んでいることがあり、これらのバッファには Direct3DDevice8.GetBackBuffer または Direct3DSwapChain8.GetBackBuffer を使ってアクセスできる。スワップ チェーンは待ち行列として見なすことができ、この待ち行列の中では、次の Present 処理で表示されるバック バッファに常にインデックス 0 が付き、いったん表示されたバッファは待ち行列から破棄される。

このスワップ エフェクトを使用するアプリケーションでは、破棄されるバック バッファの内容を推測することはできないため、バック バッファ全体を更新した後で Present 処理を呼び出す必要がある。これは強制的なことではないが、デバッグ バージョンのランタイムは、破棄されるバック バッファの内容を任意のデータで上書きできるので、開発者はアプリケーションがバック バッファ サーフェス全体を正しく更新していることを確認できる。

フルスクリーン スワップ チェーンの場合、デバイスまたはスワップ チェーンの作成時に D3DPRESENT_PARAMETERS 構造体の FullScreen_PresentationInterval メンバに割り当てられた値によってプレゼンテーション レートが決まる。この値が D3DPRESENT_INTERVAL_IMMEDIATE でない場合、プレゼンテーションはモニタの垂直同期と同期される。ウィンドウ スワップ チェーンの場合、プレゼンテーションはコピー処理によって実装されて、常に即座に実行される。

D3DSWAPEFFECT_FLIP
スワップ チェーンには複数のバック バッファが含まれることがあり、フロント バッファを含む巡回待ち行列として見なすことができる。この待ち行列の中では、バック バッファに常に 0 から N -1 (N はバック バッファの数) までの連続した数字が付けられる。したがって、0 はプレゼンテーションされる最も古いバッファを示す。Present が呼び出されると、待ち行列が「循環」されて、フロント バッファがバック バッファ (N - 1) になり、バック バッファ 0 が新しいフロント バッファになる。

フルスクリーン スワップ チェーンの場合、デバイスまたはスワップ チェーンの作成時に D3DPRESENT_PARAMETERS 構造体の FullScreen_PresentationInterval フィールドに割り当てられた値によってプレゼンテーション レートが決まる。この値が D3DPRESENT_INTERVAL_IMMEDIATE でない場合、プレゼンテーションはモニタの垂直同期と同期される。ウィンドウ スワップ チェーンの場合、フリッピングはコピー処理によって実装され、プレゼンテーションは常に即座に実行される。

D3DSWAPEFFECT_COPY
このスワップ エフェクトは、単一のバック バッファを構成するスワップ チェーンに対してのみ指定できる。ウィンドウ スワップ チェーンの場合もフルスクリーン スワップ チェーンの場合も、ランタイムはコピーベースの Present 処理によるセマンティクスを保証する。つまり、バック バッファの内容が変更されることはなく、フリップベースの Present 処理で行われるようにフロント バッファの内容で置き換えられることはない。

ウィンドウ スワップ チェーンの場合、Present 処理によってバック バッファの内容がターゲット ウィンドウのクライアント領域に即座にコピーされる。コピー内容とディスプレイ アダプタの垂直帰線間隔との同期処理は行われないため、"テアリング" 効果が現れることがある。ウィンドウ アプリケーションでは、そのようなテアリング効果を消したり最小限に抑えるために、D3DSWAPEFFECT_COPY_VSYNC を使うことができる。

フルスクリーン スワップ チェーンの場合、ランタイムはフリップ処理とコピー処理の組み合わせ (必要に応じて、隠しバック バッファでサポートされる) を使って Present 処理を行う。したがって、プレゼンテーションはディスプレイ アダプタの垂直帰線と同期され、そのレートは選択されたプレゼンテーション間隔によって制御される。ただし、D3DPRESENT_INTERVAL_IMMEDIATE フラグで指定されたスワップ チェーンは例外である。D3DPRESENT_PARAMETERS 構造体の FullScreen_PresentationInterval メンバの説明を参照すること。この場合、Present 処理は垂直帰線を待機せずに、バック バッファの内容をフロント バッファに直接コピーする。

D3DSWAPEFFECT_COPY_VSYNC
D3DSWAPEFFECT_COPY と同様、このスワップ エフェクトは、単一のバック バッファで構成されるスワップ チェーンでのみ使用でき、上の D3DSWAPEFFECT_COPY で説明したように、スワップ チェーンに適用される Present 処理がコピー セマンティクスを提示することが保証される。

ウィンドウ スワップ チェーンの場合、Present 処理によってバック バッファの内容がターゲット ウィンドウのクライアント領域に即座にコピーされる。アダプタがディスプレイ上の転送先の矩形内でスキャンしている間、ランタイムはコピー処理を避けてテアリング効果を排除しようとする。また、ランタイムは、アダプタのリフレッシュ間隔の間にコピー処理をせいぜい 1 回実行して、プレゼンテーションの頻度を制限する。ただし、アダプタがラスタ ステータスの報告機能をサポートしていない場合には、スワップ チェーンは D3DSWAPEFFECT_COPY スワップ エフェクトで作成されたかのような働きをする。D3DCAPS8 の Caps メンバについては、D3DCAPS_READ_SCANLINE フラグ値の説明を参照すること。

フルスクリーン スワップ チェーンの場合、D3DSWAPEFFECT_COPY_VSYNC は D3DSWAPEFFECT_COPY と同じである。ただし、D3DPRESENT_INTERVAL_IMMEDIATE フラグは、D3DSWAPEFFECT_COPY_VSYNC と共に使用した場合には何も効果がない。D3DPRESENT_PARAMETERS 構造体の FullScreen_PresentationInterval メンバの説明を参照すること。

注意

Present を呼び出した後のバック バッファの状態は、各スワップ エフェクトによって明確に定義されており、Microsoft® Direct3D® デバイスがフルスクリーン スワップ チェーンとウィンドウ スワップ チェーンのどちらで作成されたかによって、この状態が影響を受けることはない。特に、D3DSWAPEFFECT_FLIP スワップ エフェクトはウィンドウでもフルスクリーンでも同じように動作し、Direct3D ランタイムは外部バッファを作成することでこれを保証している。結果として、そのような悪影響を回避できる場合には、常にアプリケーションで D3DSWAPEFFECT_DISCARD を使うことを推奨する。メモリの消費およびパフォーマンスのポイントにおいて、このスワップ チェーンは常に最も効率的であることが理由である。

参照

Direct3DDevice8.Reset、D3DPRESENT_PARAMETERS


CONST_D3DTAFLAGS

テクスチャ ブレンディング ステージを規定するために使用するテクスチャ引数フラグを定義する。

詳細については、「テクスチャ引数フラグ」を参照すること。


CONST_D3DTEXOPCAPSFLAGS

テクスチャ ブレンディング処理能力を定義する。

Enum CONST_D3DTEXOPCAPSFLAGS
    D3DTEXOPCAPS_DISABLE                   =        1
    D3DTEXOPCAPS_SELECTARG1                =        2
    D3DTEXOPCAPS_SELECTARG2                =        4
    D3DTEXOPCAPS_MODULATE                  =        8
    D3DTEXOPCAPS_MODULATE2X                =       16 (&H10)
    D3DTEXOPCAPS_MODULATE4X                =       32 (&H20)
    D3DTEXOPCAPS_ADD                       =       64 (&H40)
    D3DTEXOPCAPS_ADDSIGNED                 =      128 (&H80)
    D3DTEXOPCAPS_ADDSIGNED2X               =      256 (&H100)
    D3DTEXOPCAPS_SUBTRACT                  =      512 (&H200)
    D3DTEXOPCAPS_ADDSMOOTH                 =     1024 (&H400)
    D3DTEXOPCAPS_BLENDDIFFUSEALPHA         =     2048 (&H800)
    D3DTEXOPCAPS_BLENDTEXTUREALPHA         =     4096 (&H1000)
    D3DTEXOPCAPS_BLENDFACTORALPHA          =     8192 (&H2000)
    D3DTEXOPCAPS_BLENDTEXTUREALPHAPM       =    16384 (&H4000)
    D3DTEXOPCAPS_BLENDCURRENTALPHA         =    32768 (&H8000)
    D3DTEXOPCAPS_PREMODULATE               =    65536 (&H10000)
    D3DTEXOPCAPS_MODULATEALPHA_ADDCOLOR    =   131072 (&H20000)
    D3DTEXOPCAPS_MODULATECOLOR_ADDALPHA    =   262144 (&H40000)
    D3DTEXOPCAPS_MODULATEINVALPHA_ADDCOLOR =   524288 (&H80000)
    D3DTEXOPCAPS_MODULATEINVCOLOR_ADDALPHA =  1048576 (&H100000)
    D3DTEXOPCAPS_BUMPENVMAP                =  2097152 (&H200000)
    D3DTEXOPCAPS_BUMPENVMAPLUMINANCE       =  4194304 (&H400000)
    D3DTEXOPCAPS_DOTPRODUCT3               =  8388608 (&H800000)
    D3DTEXOPCAPS_MULTIPLYADD               = 16777216 (&H1000000)
    D3DTEXOPCAPS_LERP                      = 33554432 (&H2000000)
End Enum

定数

D3DTEXOPCAPS_DISABLE
D3DTOP_DISABLE テクスチャ ブレンディング処理がサポートされる。
D3DTEXOPCAPS_SELECTARG1
D3DTOP_SELECTARG1 テクスチャ ブレンディング処理がサポートされる。
D3DTEXOPCAPS_SELECTARG2
D3DTOP_SELECTARG2 テクスチャ ブレンディング処理がサポートされる。
D3DTEXOPCAPS_MODULATE
D3DTOP_MODULATE テクスチャ ブレンディング処理がサポートされる。
D3DTEXOPCAPS_MODULATE2X
D3DTOP_MODULATE2X テクスチャ ブレンディング処理がサポートされる。
D3DTEXOPCAPS_MODULATE4X
D3DTOP_MODULATE4X テクスチャ ブレンディング処理がサポートされる。
D3DTEXOPCAPS_ADD
D3DTOP_ADD テクスチャ ブレンディング処理がサポートされる。
D3DTEXOPCAPS_ADDSIGNED
D3DTOP_ADDSIGNED テクスチャ ブレンディング処理がサポートされる。
D3DTEXOPCAPS_ADDSIGNED2X
D3DTOP_ADDSIGNED2X テクスチャ ブレンディング処理がサポートされる。
D3DTEXOPCAPS_SUBTRACT
D3DTOP_SUBTRACT テクスチャ ブレンディング処理がサポートされる。
D3DTEXOPCAPS_ADDSMOOTH
D3DTOP_ADDSMOOTH テクスチャ ブレンディング処理がサポートされる。
D3DTEXOPCAPS_BLENDDIFFUSEALPHA
D3DTOP_BLENDDIFFUSEALPHA テクスチャ ブレンディング処理がサポートされる。
D3DTEXOPCAPS_BLENDTEXTUREALPHA
D3DTOP_BLENDTEXTUREALPHA テクスチャ ブレンディング処理がサポートされる。
D3DTEXOPCAPS_BLENDFACTORALPHA
D3DTOP_BLENDFACTORALPHA テクスチャ ブレンディング処理がサポートされる。
D3DTEXOPCAPS_BLENDTEXTUREALPHAPM
D3DTOP_BLENDTEXTUREALPHAPM テクスチャ ブレンディング処理がサポートされる。
D3DTEXOPCAPS_BLENDCURRENTALPHA
D3DTOP_BLENDCURRENTALPHA テクスチャ ブレンディング処理がサポートされる。
D3DTEXOPCAPS_PREMODULATE
D3DTOP_PREMODULATE テクスチャ ブレンディング処理がサポートされる。
D3DTEXOPCAPS_MODULATEALPHA_ADDCOLOR
D3DTOP_MODULATEALPHA_ADDCOLOR テクスチャ ブレンディング処理がサポートされる。
D3DTEXOPCAPS_MODULATECOLOR_ADDALPHA
D3DTOP_MODULATECOLOR_ADDALPHA テクスチャ ブレンディング処理がサポートされる。
D3DTEXOPCAPS_MODULATEINVALPHA_ADDCOLOR
D3DTOP_MODULATEINVALPHA_ADDCOLOR テクスチャ ブレンディング処理がサポートされる。
D3DTEXOPCAPS_MODULATEINVCOLOR_ADDALPHA
D3DTOP_MODULATEINVCOLOR_ADDALPHA テクスチャ ブレンディング処理がサポートされる。
D3DTEXOPCAPS_BUMPENVMAP
D3DTOP_BUMPENVMAP テクスチャ ブレンディング処理がサポートされる。
D3DTEXOPCAPS_BUMPENVMAPLUMINANCE
D3DTOP_BUMPENVMAPLUMINANCE テクスチャ ブレンディング処理がサポートされる。
D3DTEXOPCAPS_DOTPRODUCT3
D3DTOP_DOTPRODUCT3 テクスチャ ブレンディング処理がサポートされる。
D3DTEXOPCAPS_MULTIPLYADD
D3DTOP_MULTIPLYADD テクスチャ ブレンディング処理がサポートされる。
D3DTEXOPCAPS_LERP
D3DTOP_LERP テクスチャ ブレンディング処理がサポートされる。

注意

これらのフラグは、組み合わせて、D3DCAPS8 の TextureOpCaps メンバで使用できる。

テクスチャ処理の定義については、「CONST_D3DTEXTUREOP」を参照すること。

参照

D3DCAPS8、CONST_D3DTEXTUREOP


CONST_D3DTEXTUREADDRESS

サポートされているテクスチャ アドレッシング モードを記述する定数を定義する。

Enum CONST_D3DTEXTUREADDRESS
    D3DTADDRESS_WRAP       = 1
    D3DTADDRESS_MIRROR     = 2
    D3DTADDRESS_CLAMP      = 3
    D3DTADDRESS_BORDER     = 4
    D3DTADDRESS_MIRRORONCE = 5
End Enum

定数

D3DTADDRESS_WRAP
すべての整数接合点でテクスチャを貼り合わせる。たとえば、u の値が 0 から 3 までの場合、テクスチャは 3 回繰り返され、ミラーリングは行われない。
D3DTADDRESS_MIRROR
すべての整数接合点でテクスチャのフリッピングが起こることを除けば、D3DTADDRESS_WRAP と同様である。たとえば、u の値が 0 から 1 の範囲にある場合、テクスチャの処理は通常どおりに行われるが、1 から 2 の範囲にある場合はフリップ (ミラー化) が行われ、2 から 3 の範囲の場合は再び通常の処理が行われる。以後、このパターンが繰り返される。
D3DTADDRESS_CLAMP
範囲 [0.0, 1.0] の外側のテクスチャ座標が、それぞれ、0.0 と 1.0 のテクスチャ カラーに設定される。
D3DTADDRESS_BORDER
範囲 [0.0, 1.0] の外側のテクスチャ座標は、境界色に設定される。
D3DTADDRESS_MIRRORONCE
D3DTADDRESS_MIRROR および D3DTADDRESS_CLAMP に類似している。テクスチャ座標の絶対値を取得し (0 を中心にミラーリングされ)、最大値に制限する。最も一般的な用途はボリューム テクスチャで使用することである。ボリューム テクスチャでは、完全な D3DTADDRESS_MIRRORONCE テクスチャアドレッシング モードは必要ないが、データは 1 つの軸に沿って対称である。

注意

これらのフラグは、CONST_D3DTEXTURESTAGESTATETYPE 列挙の D3DTSS_ADDRESSU、D3DTSS_ADDRESSV、および D3DTSS_ADDRESSW の各テクスチャ ステージ ステートの値を設定するために使われる。

参照

CONST_D3DTEXTURESTAGESTATETYPE


CONST_D3DTEXTUREFILTERTYPE

テクスチャ ステージに対するテクスチャ フィルタリング モードを定義する。

Enum CONST_D3DTEXTUREFILTERTYPE
    D3DTEXF_NONE          = 0
    D3DTEXF_POINT         = 1
    D3DTEXF_LINEAR        = 2
    D3DTEXF_ANISOTROPIC   = 3
    D3DTEXF_FLATCUBIC     = 4
    D3DTEXF_GAUSSIANCUBIC = 5
End Enum

定数

D3DTEXF_NONE
ミップマップ処理を無効にする。ラスタライザは代わりに拡大フィルタを使用する。
D3DTEXF_POINT
テクスチャの拡大フィルタまたは縮小フィルタとして使われるポイント フィルタリング。希望のピクセル値に最も近い座標を持つテクセルを使用する。

ミップマップ レベル間で使われるテクスチャ フィルタは、最近ポイント ミップマップ フィルタである。ラスタライザは最も近いミップマップ テクスチャのテクセルからの色を使用する。

D3DTEXF_LINEAR
テクスチャの拡大フィルタまたは縮小フィルタとして使われるバイリニア補間フィルタリング。目的のピクセルを囲む 2 × 2 領域のテクセルの重み付き平均を使用する。

ミップマップ レベル間で使われるテクスチャ フィルタは、トライリニア ミップマップ補間である。ラスタライザは、最も近いミップマップ テクスチャ 2 点からのテクセルを使用して、ピクセル色を線形補間する。

D3DTEXF_ANISOTROPIC
テクスチャの拡大フィルタまたは縮小フィルタとして使われる異方性テクスチャ フィルタリング。テクスチャ ポリゴンとスクリーン平面間の角度の相違により起こる歪みを補正する。
D3DTEXF_FLATCUBIC
テクスチャ拡大フィルタとして使われる平面 3 次フィルタリング。
D3DTEXF_GAUSSIANCUBIC
テクスチャ拡大フィルタとして使われるガウス 3 次フィルタリング。

注意

デバイスの有効なフィルタリング モードがすべてボリューム マップに適用されるわけではない。一般的に、ボリューム マップでは、D3DTEXF_POINT および D3DTEXF_LINEAR 拡大フィルタがサポートされている。D3DPTEXTURECAPS_MIPVOLUMEMAP が設定されている場合、ボリュームマップでは、D3DTEXF_POINT ミップマップ フィルタと、D3DTEXF_POINT および D3DTEXF_LINEAR 縮小フィルタがサポートされる。デバイスは、ボリューム マップの D3DTEXF_LINEAR ミップマップ フィルタをサポートする場合と、しない場合がある。DirectX 8 デバイスが 2D マップの異方性フィルタリングをサポートしている場合には、必ずしもボリューム マップの異方性フィルタリングをサポートしているわけではない。ただし、異方性フィルタリングがサポートされていない場合、異方性フィルタリングを使用するアプリケーションでは、最も有効なフィルタリング (線形など) を受け取る。

テクスチャ ステージの拡大フィルタを設定するには、Direct3DDevice8.SetTextureStageState メソッドを呼び出し、第 2 パラメータとして D3DTSS_MAGFILTER レンダリング ステートを指定し、第 3 パラメータとしてこの列挙のメンバのいずれかを指定する。

テクスチャ ステージの縮小フィルタを設定するには、SetTextureStageState メソッドを呼び出し、第 2 パラメータとして D3DTSS_MINFILTER レンダリング ステートを指定し、第 3 パラメータとしてこの列挙のメンバのいずれかを指定する。

ミップマップ レベル間で使用するテクスチャ フィルタを設定するには、SetTextureStageState メソッドを呼び出し、第 2 パラメータとして D3DTSS_MIPFILTER レンダリング ステートを指定し、第 3 パラメータとしてこの列挙のメンバのいずれかを指定する。

参照

D3DCAPS8、CONST_D3DTEXTURESTAGESTATETYPE


CONST_D3DTEXTUREOP

ステージごとのテクスチャ ブレンディング処理を定義する。

Enum CONST_D3DTEXTUREOP
    D3DTOP_DISABLE                   =  1
    D3DTOP_SELECTARG1                =  2
    D3DTOP_SELECTARG2                =  3
    D3DTOP_MODULATE                  =  4
    D3DTOP_MODULATE2X                =  5
    D3DTOP_MODULATE4X                =  6
    D3DTOP_ADD                       =  7
    D3DTOP_ADDSIGNED                 =  8
    D3DTOP_ADDSIGNED2X               =  9
    D3DTOP_SUBTRACT                  = 10
    D3DTOP_ADDSMOOTH                 = 11
    D3DTOP_BLENDDIFFUSEALPHA         = 12
    D3DTOP_BLENDTEXTUREALPHA         = 13
    D3DTOP_BLENDFACTORALPHA          = 14
    D3DTOP_BLENDTEXTUREALPHAPM       = 15
    D3DTOP_BLENDCURRENTALPHA         = 16 (&H10)
    D3DTOP_PREMODULATE               = 17 (&H11)
    D3DTOP_MODULATEALPHA_ADDCOLOR    = 18 (&H12)
    D3DTOP_MODULATECOLOR_ADDALPHA    = 19 (&H13)
    D3DTOP_MODULATEINVALPHA_ADDCOLOR = 20 (&H14)
    D3DTOP_MODULATEINVCOLOR_ADDALPHA = 21 (&H15)
    D3DTOP_BUMPENVMAP                = 22 (&H16)
    D3DTOP_BUMPENVMAPLUMINANCE       = 23 (&H17)
    D3DTOP_DOTPRODUCT3               = 24 (&H18)
    D3DTOP_MULTIPLYADD               = 25 (&H19)
    D3DTOP_LERP                      = 26 (&H1A)
End Enum

定数

制御メンバ
D3DTOP_DISABLE
このテクスチャ ステージおよびより高いインデックスを持つステージからの出力を、すべて無効にする。テクスチャ マッピングを無効にするには、この処理を最初のテクスチャ ステージ (ステージ 0) に対して設定する。カラー処理が有効のときに、アルファ処理を無効にすることはできない。カラー ブレンディングが有効のときにアルファ処理を D3DTOP_DISABLE に設定すると、その動作は不定である。
D3DTOP_SELECTARG1
このテクスチャ ステージの最初の色引数またはアルファ引数を、変更しないで出力として使用する。この処理は、D3DTSS_COLOROP テクスチャ ステージ ステートで使用すると色引数に影響を与え、D3DTSS_ALPHAOP で使用した場合にはアルファ引数に影響を与える。

D3DTOP_SELECTARG2
このテクスチャ ステージの 2 番目の色引数またはアルファ引数を、変更しないで出力として使用する。この処理は、D3DTSS_COLOROP テクスチャ ステージ ステートで使用すると色引数に影響を与え、D3DTSS_ALPHAOP で使用した場合にはアルファ引数に影響を与える。

乗算メンバ
D3DTOP_MODULATE
引数の成分を乗算する。

D3DTOP_MODULATE2X
引数の成分を乗算し、その積を左に 1 ビットだけシフト (2 で乗算するのと同じ) して明るくする。

D3DTOP_MODULATE4X
引数の成分を乗算し、その積を左に 2 ビットだけシフト (4 で乗算するのと同じ) して明るくする。

加減算メンバ
D3DTOP_ADD
引数の成分を加算する。

D3DTOP_ADDSIGNED
バイアス値 -0.5 を引数の成分に加算し、値の有効範囲を -0.5 から 0.5 にする。

D3DTOP_ADDSIGNED2X
バイアス値 -0.5 を引数の成分に加算し、その積を左に 1 ビットだけシフトする。

D3DTOP_SUBTRACT
第 1 引数の成分から、対応する第 2 引数の成分を減算する。

D3DTOP_ADDSMOOTH
第 1 および第 2 引数を加算し、次にその積を合計から減算する。

線形アルファ ブレンディング メンバ
D3DTOP_BLENDDIFFUSEALPHA、D3DTOP_BLENDTEXTUREALPHA、D3DTOP_BLENDFACTORALPHA、および D3DTOP_BLENDCURRENTALPHA
各頂点からの補間アルファ (D3DTOP_BLENDDIFFUSEALPHA)、このステージのテクスチャからのアルファ (D3DTOP_BLENDTEXTUREALPHA)、D3DRS_TEXTUREFACTOR レンダリング ステートで設定されるスカラー アルファ (D3DTOP_BLENDFACTORALPHA)、または前のテクスチャ ステージからのアルファ (D3DTOP_BLENDCURRENTALPHA) を使用して、このテクスチャ ステージの線形ブレンディングを行う。

D3DTOP_BLENDTEXTUREALPHAPM
あらかじめ乗算されたアルファを使用するテクスチャ ステージの線形ブレンディングを実行する。

スペキュラ マッピング メンバ
D3DTOP_PREMODULATE
現在のテクスチャ ステージと次のテクスチャ ステージの間で乗算を行う。
D3DTOP_MODULATEALPHA_ADDCOLOR
第 1 引数のアルファを使用して第 2 引数の色を乗算し、その結果を第 1 引数に加算する。この処理は、カラー処理 (D3DTSS_COLOROP) でのみサポートされる。

D3DTOP_MODULATECOLOR_ADDALPHA
引数を乗算し、第 1 引数のアルファを加算する。この処理は、カラー処理 (D3DTSS_COLOROP) でのみサポートされる。

D3DTOP_MODULATEINVALPHA_ADDCOLOR
D3DTOP_MODULATEALPHA_ADDCOLOR に類似しているが、第 1 引数のアルファの逆数を使用するところが異なる。この処理は、カラー処理 (D3DTSS_COLOROP) でのみサポートされる。

D3DTOP_MODULATEINVCOLOR_ADDALPHA
D3DTOP_MODULATECOLOR_ADDALPHA に類似しているが、第 1 引数の色の逆数を使用するところが異なる。この処理は、カラー処理 (D3DTSS_COLOROP) でのみサポートされる。

バンプマッピング メンバ
D3DTOP_BUMPENVMAP
次のテクスチャ ステージの環境マップ (輝度なし) による、ピクセル単位のバンプ マッピングを実行する。この処理は、カラー処理 (D3DTSS_COLOROP) でのみサポートされる。
D3DTOP_BUMPENVMAPLUMINANCE
次のテクスチャ ステージの環境マップ (輝度あり) による、ピクセル単位のバンプ マッピングを実行する。この処理は、カラー処理 (D3DTSS_COLOROP) でのみサポートされる。
D3DTOP_DOTPRODUCT3
各引数の要素を (符号付要素として) 乗算して積を加算し、得られた合計値をアルファを含むすべてのカラー チャネルに複製する。この処理がサポートされるのはカラー処理とアルファ処理に対してである。

DirectX 6.0 および 7.0 のマルチテクスチャ処理では、上記の入力は、符号付きデータをシミュレートするため、使用する前にすべて 0.5 シフトされ (y = x - 0.5)、結果のスカラーは正の値に制限され、3 つの出力チャネルすべてに複製される。また、カラー処理としては、RGB 成分を更新したアルファを更新しないことに注意すること。

ただし、DirectX 8.0 シェーダでは、出力を .rgb または .a コンポーネント、またはその両方 (デフォルト) にルーティングすることを指定できる。アルファ チャネルで個別のスカラー処理を指定することもできる。

三項テクスチャ ブレンディング メンバ
D3DTOP_MULTIPLYADD
積和演算を実行する。最後の 2 つの引数を取り、これらを乗算し、残りの入力/ソース引数に加算し、この合計を結果に配置する。

SRGBA = Arg1 + Arg2 * Arg3

D3DTOP_LERP
第 1 ソース引数で指定された割合で、第 2 および第 3 ソース引数の間を線形補間する。

SRGBA = (Arg1) * Arg2 + (1-Arg1) * Arg3

注意

この型のメンバは、D3DTSS_COLOROP または D3DTSS_ALPHAOP テクスチャ ステージ ステート値を使用して Direct3DDevice8.SetTextureStageState メソッドを呼び出し、カラー処理やアルファ処理を設定するときに使われる。

上の式では、SRGBA はテクスチャ処理で作成される RGBA 色、Arg1 および Arg2 はテクスチャ引数の完全 RGBA 色である。引数の個々の成分は、添字を付けて表記される。たとえば、引数 1 のアルファ成分は Arg1A として表される。

参照

CONST_D3DTEXTURESTAGESTATETYPE


CONST_D3DTEXTURESTAGESTATETYPE

テクスチャ ステージ ステートを定義する。

Enum CONST_D3DTEXTURESTAGESTATETYPE
    D3DTSS_COLOROP               =  1
    D3DTSS_COLORARG1             =  2
    D3DTSS_COLORARG2             =  3
    D3DTSS_ALPHAOP               =  4
    D3DTSS_ALPHAARG1             =  5
    D3DTSS_ALPHAARG2             =  6
    D3DTSS_BUMPENVMAT00          =  7
    D3DTSS_BUMPENVMAT01          =  8
    D3DTSS_BUMPENVMAT10          =  9
    D3DTSS_BUMPENVMAT11          = 10
    D3DTSS_TEXCOORDINDEX         = 11
    D3DTSS_ADDRESSU              = 13
    D3DTSS_ADDRESSV              = 14
    D3DTSS_BORDERCOLOR           = 15
    D3DTSS_MAGFILTER             = 16 (&H10)
    D3DTSS_MINFILTER             = 17 (&H11)
    D3DTSS_MIPFILTER             = 18 (&H12)
    D3DTSS_MIPMAPLODBIAS         = 19 (&H13)
    D3DTSS_MAXMIPLEVEL           = 20 (&H14)
    D3DTSS_MAXANISOTROPY         = 21 (&H15)
    D3DTSS_BUMPENVLSCALE         = 22 (&H16)
    D3DTSS_BUMPENVLOFFSET        = 23 (&H17)
    D3DTSS_TEXTURETRANSFORMFLAGS = 24 (&H18)
    D3DTSS_ADDRESSW              = 25 (&H19)
    D3DTSS_COLORARG0             = 26 (&H1A)
    D3DTSS_ALPHAARG0             = 27 (&H1B)
    D3DTSS_RESULTARG             = 28 (&H1C)
End Enum

定数

D3DTSS_COLOROP
テクスチャ ステージ ステートは、テクスチャ カラー ブレンディング処理であり、CONST_D3DTEXTUREOP 列挙のメンバの 1 つによって示される。最初のテクスチャ ステージ (ステージ 0) のデフォルト値は D3DTOP_MODULATE であり、それ以外のすべてのステージのデフォルト値は D3DTOP_DISABLE である。
D3DTSS_COLORARG1
テクスチャ ステージ ステートは、そのステージに対する最初の色引数であり、テクスチャ引数フラグのいずれかにより示される。デフォルトの引数は D3DTA_TEXTURE である。
D3DTSS_COLORARG2
テクスチャ ステージ ステートは、そのステージに対する第 2 の色引数であり、テクスチャ引数フラグのいずれかにより示される。デフォルトの引数は D3DTA_CURRENT である。
D3DTSS_ALPHAOP
テクスチャ ステージ ステートはテクスチャ アルファ ブレンディング処理であり、CONST_D3DTEXTUREOP 列挙のメンバの 1 つによって示される。最初のテクスチャ ステージ (ステージ 0) のデフォルト値は D3DTOP_SELECTARG1 であり、それ以外のすべてのステージのデフォルト値は D3DTOP_DISABLE である。
D3DTSS_ALPHAARG1
テクスチャ ステージ ステートはそのステージに対する最初のアルファ引数であり、テクスチャ引数フラグのいずれかにより示される。デフォルトの引数は D3DTA_TEXTURE である。そのステージにテクスチャが設定されていない場合は、D3DTA_DIFFUSE がデフォルトの引数となる。
D3DTSS_ALPHAARG2
テクスチャ ステージ ステートはそのステージに対する第 2 のアルファ引数であり、テクスチャ引数フラグのいずれかにより示される。デフォルトの引数は D3DTA_CURRENT である。
D3DTSS_BUMPENVMAT00
テクスチャ ステージ ステートは、バンプ マッピング行列の [0][0] 係数に対する値である。デフォルト値は 0.0 である。
D3DTSS_BUMPENVMAT01
テクスチャ ステージ ステートは、バンプ マッピング行列の [0][1] 係数に対する値である。デフォルト値は 0.0 である。
D3DTSS_BUMPENVMAT10
テクスチャ ステージ ステートは、バンプ マッピング行列の [1][0] 係数に対する値である。デフォルト値は 0.0 である。
D3DTSS_BUMPENVMAT11
テクスチャ ステージ ステートは、バンプ マッピング行列の [1][1] 係数に対する値である。デフォルト値は 0.0 である。
D3DTSS_TEXCOORDINDEX
このテクスチャ ステージで使用するために設定されたテクスチャ座標インデックス。このフラグは、固定機能頂点処理でのみ使用する。たとえば、頂点シェーダでは使用しない。頂点シェーダを使ってレンダリングするときは、各ステージのテクスチャ インデックスをデフォルト値に設定する必要がある。各ステージのデフォルトのインデックスは、ステージ インデックスと同じである。このステートには、このテクスチャ ステージで使用する各頂点に対する座標セットのゼロから始まるインデックスを設定する。頂点 1 個に対して最大 8 セットまでのテクスチャ座標を設定できる。頂点が、指定されたインデックスのテクスチャ座標セットを含んでいない場合は、u および v 座標 (0,0) がデフォルトで使用される。

また、アプリケーションでは、(設定されるインデックスとの論理和として) 以下のフラグのいずれかを設定して、テクスチャ トランスフォーム用の入力テクスチャ座標を自動的に生成するよう Microsoft® Direct3D® に要求できる。ゼロに解決される D3DTSS_TCI_PASSTHRU を除き、設定されるインデックスと以下のフラグのいずれかを使用すると、テクスチャ ラッピング モードの決定にインデックスが厳密に使用される。CONST_D3DTSS_TCI_FLAGS 列挙で定義されているこれらのフラグは、環境マッピングを行う場合に最も有効である。

D3DTSS_TCI_PASSTHRU
頂点フォーマット内の指定されたテクスチャ座標を使用する。この値はゼロに解決される。
D3DTSS_TCI_CAMERASPACENORMAL
このステージのテクスチャ トランスフォームに対する入力テクスチャ座標として、カメラ空間にトランスフォームされた頂点法線を使用する。
D3DTSS_TCI_CAMERASPACEPOSITION
このステージのテクスチャ トランスフォームに対する入力テクスチャ座標として、カメラ空間にトランスフォームされた頂点位置を使用する。
D3DTSS_TCI_CAMERASPACEREFLECTIONVECTOR
このステージのテクスチャ トランスフォームに対する入力テクスチャ座標として、カメラ空間にトランスフォームされた反射ベクトルを使用する。反射ベクトルは入力頂点位置座標と法線ベクトルから計算される。
D3DTSS_ADDRESSU
CONST_D3DTEXTUREADDRESS 列挙のメンバ。u 座標で使用するテクスチャ アドレッシング方法を選択する。デフォルト値は D3DTADDRESS_WRAP である。
D3DTSS_ADDRESSV
CONST_D3DTEXTUREADDRESS 列挙のメンバ。v 座標で使用するテクスチャ アドレッシング方法を選択する。デフォルト値は D3DTADDRESS_WRAP である。
D3DTSS_BORDERCOLOR
[0.0, 1.0] の範囲の外にあるテクスチャ座標をラスタ化するときに使用する色を記述する値。デフォルト色は &H00000000 である。
D3DTSS_MAGFILTER
テクスチャをプリミティブにレンダリングするときに使用するテクスチャ拡大フィルタを示す CONST_D3DTEXTUREFILTERTYPE 列挙のメンバ。デフォルト値は D3DTEXF_POINT である。
D3DTSS_MINFILTER
テクスチャをプリミティブにレンダリングするときに使用するテクスチャ縮小フィルタを示す CONST_D3DTEXTUREFILTERTYPE 列挙のメンバ。デフォルト値は D3DTEXF_POINT である。
D3DTSS_MIPFILTER
ミップマップ レベル間で使用するテクスチャ フィルタを示す CONST_D3DTEXTUREFILTERTYPE 列挙のメンバ。デフォルト値は D3DTFN_POINT である。
D3DTSS_MIPMAPLODBIAS
ミップマップに対する詳細バイアスのレベル。これを利用すると、テクスチャに質量感を与えたり、ぼやけた感じを与えることができる。デフォルト値は 0.0 である。

バイアスの各単位 (+/-1.0) は、正確に 1 ミップマップ レベルごとに選択範囲を変更する。負のバイアスは、使用するミップマップ レベルを大きくする。結果はシャープになるが、ぎざぎざしたイメージになる。正のバイアスは、使用するミップマップ レベルを小さくする。結果はぼやけたイメージになる。また、正のバイアスを指定すると、参照されるテクスチャ データが少なくなり、システムによってはパフォーマンスが向上する場合がある。

D3DTSS_MAXMIPLEVEL
ミップマップ チェーンの先頭からのインデックスとして示された、アプリケーションで許容する最大ミップマップ詳細レベル。低い値の方が、ミップマップ チェーン内の高い詳細レベルを表す。ゼロがデフォルト値で、全レベルが使用可能であることを示す。ゼロ以外の値は、指定されたインデックスより高い詳細レベルのミップマップを表示できないことを示す。
D3DTSS_MAXANISOTROPY
異方性レベルの最大値。デフォルト値は 1 である。
D3DTSS_BUMPENVLSCALE
バンプ マップ輝度用のスケール。デフォルト値は 0.0 である。
D3DTSS_BUMPENVLOFFSET
バンプ マップ輝度用のオフセット。デフォルト値は 0.0 である。
D3DTSS_TEXTURETRANSFORMFLAGS
このテクスチャ ステージのテクスチャ座標のトランスフォームを制御する CONST_D3DTEXTURETRANSFORMFLAGS 列挙のメンバ。デフォルト値は D3DTTFF_DISABLE である。
D3DTSS_ADDRESSW
CONST_D3DTEXTUREADDRESS 列挙のメンバ。w 座標で使用するテクスチャ アドレッシング方法を選択する。デフォルト値は D3DTADDRESS_WRAP である。
D3DTSS_COLORARG0
三項演算 (積和および線形補間) の 3 番目の色オペランドの設定。テクスチャ引数フラグのいずれかによって識別される。この設定は、D3DTEXOPCAPS_MULTIPLYADD または D3DTEXOPCAPS_LERP デバイス能力が存在する場合にサポートされる。

読み書き用のテンポラリ レジスタの色を選択するには、D3DTA_TEMP を指定する。D3DTA_TEMP は、D3DPMISCCAPS_TSSARGTEMP デバイス能力が存在する場合にサポートされる。レジスタのデフォルト値は (0.0, 0.0, 0.0, 0.0) である。

D3DTSS_ALPHAARG0
三項演算 (積和および線形補間) のアルファ チャネル セレクタ オペランドの設定。テクスチャ引数フラグのいずれかによって識別される。この設定は、D3DTEXOPCAPS_MULTIPLYADD または D3DTEXOPCAPS_LERP デバイス能力が存在する場合にサポートされる。

読み書き用のテンポラリ レジスタの色を選択するには、D3DTA_TEMP を指定する。D3DTA_TEMP は、D3DPMISCCAPS_TSSARGTEMP デバイス能力が存在する場合にサポートされる。レジスタのデフォルト値は (0.0, 0.0, 0.0, 0.0) である。

D3DTSS_RESULTARG
このステージの結果のデスティネーション レジスタを選択するための設定。テクスチャ引数フラグのいずれかによって識別される。この値は、D3DTA_CURRENT (デフォルト値) または D3DTA_TEMP に設定できる。D3DTA_TEMP は、入力引数として以降のステージに読み込むことができる単一のテンポラリ レジスタである。フォグ ブレンダおよびフレーム バッファに渡される最終的な色は D3DTA_CURRENT から取得されるので、最後にアクティブなテクスチャ ステージ ステートはカレントへの書き込みに設定しなければならない。

この設定は、D3DPMISCCAPS_TSSARGTEMP デバイス能力が存在する場合にサポートされる。

注意

この列挙のメンバは、テクスチャ ステート値を取得および設定する Direct3DDevice8.GetTextureStageState メソッドと Direct3DDevice8.SetTextureStageState メソッドで使用される。

D3DTSS_BUMPENVMAT00、D3DTSS_BUMPENVMAT01、D3DTSS_BUMPENVMAT10、および D3DTSS_BUMPENVMAT11 の各バンプ マッピング行列係数の有効範囲は、-8.0 以上 8.0 未満である。この範囲を数学的には [-8.0, 8.0] と表記する。

参照

Direct3DDevice8.GetTextureStageState、Direct3DDevice8.SetTextureStageState


CONST_D3DTEXTURETRANSFORMFLAGS

テクスチャ ステージ ステートの値を定義する。

Enum CONST_D3DTEXTURETRANSFORMFLAGS
    D3DTTFF_DISABLE   =   0
    D3DTTFF_COUNT1    =   1
    D3DTTFF_COUNT2    =   2
    D3DTTFF_COUNT3    =   3
    D3DTTFF_COUNT4    =   4
    D3DTTFF_PROJECTED = 256 (&H100)
End Enum

定数

D3DTTFF_DISABLE
テクスチャ座標はラスタライザに直接渡される。
D3DTTFF_COUNT1
ラスタライザは、1D のテクスチャ座標を想定する。
D3DTTFF_COUNT2
ラスタライザは、2D のテクスチャ座標を想定する。
D3DTTFF_COUNT3
ラスタライザは、3D のテクスチャ座標を想定する。
D3DTTFF_COUNT4
ラスタライザは、4D のテクスチャ座標を想定する。
D3DTTFF_PROJECTED
テクスチャ座標は、ラスタライザに渡される前に最後の要素ですべて分割される。たとえば、このフラグが D3DTTFF_COUNT3 と共に指定されている場合、1 番目および 2 番目のテクスチャ座標は、ラスタライザに渡される前に、3 番目の座標で分割される。

注意

これらのフラグは、D3DTSS_TEXTURETRANSFORMFLAGS テクスチャ ステージ ステートの値に CONST_D3DTEXTURESTAGESTATETYPE 列挙を設定するために使われる。

参照

CONST_D3DTEXTURESTAGESTATETYPE


CONST_D3DTRANSFORMSTATETYPE

トランスフォーム ステートの値を記述する定数を定義する。

Enum CONST_D3DTRANSFORMSTATETYPE
    D3DTS_WORLD      =  1
    D3DTS_VIEW       =  2
    D3DTS_PROJECTION =  3
    D3DTS_WORLD1     =  4
    D3DTS_WORLD2     =  5
    D3DTS_WORLD3     =  6
    D3DTS_TEXTURE0   = 16 (&H10)
    D3DTS_TEXTURE1   = 17 (&H11)
    D3DTS_TEXTURE2   = 18 (&H12)
    D3DTS_TEXTURE3   = 19 (&H13)
    D3DTS_TEXTURE4   = 20 (&H14)
    D3DTS_TEXTURE5   = 21 (&H15)
    D3DTS_TEXTURE6   = 22 (&H16)
    D3DTS_TEXTURE7   = 23 (&H17)
End Enum

定数

D3DTS_WORLD
ワールド トランスフォーム行列として設定されるトランスフォーム行列を示す。デフォルト値は Nothing である (単位行列)。
D3DTS_VIEW
ビュー トランスフォーム行列として設定されるトランスフォーム行列を識別する。デフォルト値は NULL である (単位行列)。
D3DTS_PROJECTION
射影トランスフォーム行列として設定されるトランスフォーム行列を示す。デフォルト値は Nothing である (単位行列)。
D3DTS_WORLD1 ～ D3DTS_WORLD3
頂点フォーマットで指定された対応する行列およびブレンディング (ベータ) 加重値を用いる頂点ブレンディングに使用される、以降のトランスフォーム行列を識別する。
D3DTS_TEXTURE0 ～ D3DTS_TEXTURE7
指定されたテクスチャ ステージに設定されているトランスフォーム行列を示す。

参照

Direct3DDevice8.GetTransform、Direct3DDevice8.MultiplyTransform、Direct3DDevice8.SetTransform


CONST_D3DTSS_TCI_FLAGS

テクスチャ トランスフォーム用の入力テクスチャ座標を自動的に生成するよう Microsoft® Direct3D® に指定する定数を定義する。

Enum CONST_D3DTSS_TCI_FLAGS
    D3DTSS_TCI_PASSTHRU                    =      0
    D3DTSS_TCI_CAMERASPACENORMAL           =  65536 (&H10000)
    D3DTSS_TCI_CAMERASPACEPOSITION         = 131072 (&H20000)
    D3DTSS_TCI_CAMERASPACEREFLECTIONVECTOR = 196608 (&H30000)
End Enum

定数

D3DTSS_TCI_PASSTHRU
頂点フォーマット内の指定されたテクスチャ座標を使用する。この値はゼロに解決される。
D3DTSS_TCI_CAMERASPACENORMAL
このステージのテクスチャ トランスフォームに対する入力テクスチャ座標として、カメラ空間にトランスフォームされた頂点法線を使用する。
D3DTSS_TCI_CAMERASPACEPOSITION
このステージのテクスチャ トランスフォームに対する入力テクスチャ座標として、カメラ空間にトランスフォームされた頂点位置を使用する。
D3DTSS_TCI_CAMERASPACEREFLECTIONVECTOR
このステージのテクスチャ トランスフォームに対する入力テクスチャ座標として、カメラ空間にトランスフォームされた反射ベクトルを使用する。反射ベクトルは入力頂点位置座標と法線ベクトルから計算される。

注意

これらのフラグは、CONST_D3DTEXTURESTAGESTATETYPE 列挙の D3DTSS_TEXCOORDINDEX メンバの値を設定するために使われる。

参照

CONST_D3DTEXTURESTAGESTATETYPE


CONST_D3DUSAGEFLAGS

リソースの使用方法を定義する定数を定義する。

Enum CONST_D3DUSAGEFLAGS
    D3DUSAGE_RENDERTARGET       =   1
    D3DUSAGE_DEPTHSTENCIL       =   2
    D3DUSAGE_WRITEONLY          =   8
    D3DUSAGE_SOFTWAREPROCESSING =  16 (&H10)
    D3DUSAGE_DONOTCLIP          =  32 (&H20)
    D3DUSAGE_POINTS             =  64 (&H40)
    D3DUSAGE_RTPATCHES          = 128 (&H80)
    D3DUSAGE_NPATCHES           = 256 (&H100)
    D3DUSAGE_DYNAMIC            = 512 (&H200)
End Enum

定数

D3DUSAGE_RENDERTARGET
サーフェスがレンダリング ターゲットとして使用されることを示す。リソースは Direct3DDevice8.SetRenderTarget メソッドの RenderTarget パラメータに渡すことができる。

この使用方法は、レンダリング ターゲット リソースに自動的に適用される。

D3DUSAGE_DEPTHSTENCIL
サーフェスが深度ステンシル サーフェスとして使用されることを示す。リソースは、SetRenderTarget の NewZStencil パラメータに渡すことができる。

この使用方法は、深度ステンシル リソースに自動的に適用される。

D3DUSAGE_WRITEONLY
アプリケーションはバッファへの書き込みだけを行うことを、システムに通知する。このフラグを使用すると、ドライバは最適なメモリ領域を選択して効率的に書き込み操作やレンダリングを実行できる。この能力を利用して作成したバッファから読み出しを行おうとすると、パフォーマンスが低下することがある。

このフラグは、インデックスおよび頂点バッファ リソースに対してのみ有効である。

D3DUSAGE_SOFTWAREPROCESSING
バッファがソフトウェア処理で使用されることを示す。

このフラグは、インデックスおよび頂点バッファ リソースに対してのみ有効である。

D3DUSAGE_DONOTCLIP
頂点バッファの内容が決してクリッピングを要求しないことを示す。

このフラグは、頂点バッファ リソースに対してのみ有効である。

D3DUSAGE_POINTS
ポイント スプライトまたはインデックス付きポイント リストの描画に、頂点バッファまたはインデックス バッファを使用することを示す。
D3DUSAGE_RTPATCHES
高次サーフェスの描画に頂点バッファまたはインデックス バッファを使用することを示す。
D3DUSAGE_NPATCHES
N パッチの描画に頂点バッファまたはインデックス バッファを使用することを示す。
D3DUSAGE_DYNAMIC
頂点またはインデックス バッファが動的なメモリの使用を必要とすることを示す。この使用方法は、ドライバが配置する場所を決定できるので、ドライバにとって有効である。一般的に、静的な頂点バッファはビデオ メモリに配置され、動的な頂点バッファは AGP メモリに配置される。ほかに静的な使用方法はないことに注意する。D3DUSAGE_DYNAMIC を指定していない場合、静的な頂点バッファが作成される。D3DUSAGE_DYNAMIC は、D3DLOCK_DISCARD および D3DLOCK_NOOVERWRITE ロッキング フラグによって厳密に強制される。その結果、D3DLOCK_DISCARD および D3DLOCK_NOOVERWRITE は、D3DUSAGE_DYNAMIC で作成された頂点およびインデックス バッファに対してだけ有効となる。これらのフラグは、静的な頂点バッファに対しては有効ではない。

D3DUSAGE_DYNAMIC は、管理下の頂点およびインデックス バッファでは指定できないことに注意すること。詳細については、「リソースの管理」を参照すること。

このフラグは、インデックスおよび頂点バッファ リソースに対してのみ有効である。

参照

Direct3DDevice8.CreateCubeTexture、Direct3DDevice8.CreateIndexBuffer、Direct3DDevice8.CreateTexture、Direct3DDevice8.CreateVertexBuffer、Direct3DDevice8.CreateVolumeTexture


CONST_D3DVERTEXBLENDFLAGS

複数の行列による頂点ブレンディングの際に適用される数値または行列を制御するためのフラグを定義する。

Enum CONST_D3DVERTEXBLENDFLAGS
    D3DVBF_DISABLE     =   0
    D3DVBF_1WEIGHTS    =   1
    D3DVBF_2WEIGHTS    =   2
    D3DVBF_3WEIGHTS    =   3
    D3DVBF_TWEENING    = 255 (&HFF)
    D3DVBF_0WEIGHTS    = 256 (&H100)
End Enum

定数

D3DVBF_DISABLE
頂点ブレンディングを無効にする。D3DTS_WORLD トランスフォーム ステートによって指定されるワールド行列に対してのみ適用される。
D3DVBF_1WEIGHTS
D3DTS_WORLD および D3DTS_WORLD1 の各トランスフォーム ステートによって設定される 2 つの行列間の頂点ブレンディングを有効にする。
D3DVBF_2WEIGHTS
D3DTS_WORLD、D3DTS_WORLD1、および D3DTS_WORLD2 の各トランスフォーム ステートによって設定される 3 つの行列間の頂点ブレンディングを有効にする。
D3DVBF_3WEIGHTS
D3DTS_WORLD、D3DTS_WORLD1、D3DTS_WORLD2、および D3DTS_WORLD3 の各トランスフォーム ステートによって設定される 4 つの行列間の頂点ブレンディングを有効にする。
D3DVBF_TWEENING
頂点ブレンディングは、D3DRS_TWEENFACTOR に割り当てられた値を使って行われる。
D3DVBF_0WEIGHTS
1.0 の重みで単一の行列を使用する。

注意

これらのフラグは、CONST_D3DRENDERSTATETYPE 列挙の D3DRS_VERTEXBLEND レンダリング ステートの値を設定するために使われる。

ジオメトリ ブレンディング (複数の行列による頂点ブレンディング) では、各頂点のブレンディング (ベータ) 加重値を持つ頂点フォーマットを使用しなければならない。

参照

CONST_D3DRENDERSTATETYPE


CONST_D3DVTXPCAPSFLAGS

頂点処理の能力を定義する。

Enum CONST_D3DVTXPCAPSFLAGS
    D3DVTXPCAPS_TEXGEN            =  1
    D3DVTXPCAPS_MATERIALSOURCE7   =  2
    D3DVTXPCAPS_DIRECTIONALLIGHTS =  8
    D3DVTXPCAPS_POSITIONALLIGHTS  = 16 (&H10)
    D3DVTXPCAPS_LOCALVIEWER       = 32 (&H20)
    D3DVTXPCAPS_TWEENING          = 64 (&H40)
End Enum

定数

D3DVTXPCAPS_TEXGEN
デバイスはテクスチャ座標を生成できる。
D3DVTXPCAPS_MATERIALSOURCE7
デバイスは選択可能な頂点カラー ソースをサポートする。
D3DVTXPCAPS_DIRECTIONALLIGHTS
デバイスはディレクショナル ライトをサポートする。
D3DVTXPCAPS_POSITIONALLIGHTS
デバイスは局部ライト (ポイント ライトやスポット ライトなど) をサポートする。
D3DVTXPCAPS_LOCALVIEWER
デバイスはローカル ビューアをサポートする。
D3DVTXPCAPS_TWEENING
デバイスは頂点トゥイーニングをサポートする。

注意

これらのフラグは、組み合わせて、D3DCAPS8 の VertexProcessingCaps メンバで使用できる。

参照

D3DCAPS8


CONST_D3DWRAPBIAS

テクスチャ座標セットのゼロから始まる整数値に基づいて、テクスチャ ラッピングを有効または無効にする定数を定義する。

Enum CONST_D3DWRAPBIAS
    D3DRENDERSTATE_WRAPBIAS = 128 (&H80)
End Enum

定数

D3DRENDERSTATE_WRAPBIAS
ラップ バイアス。実装の詳細については、「注意」を参照すること。

注意

Microsoft® Direct3D® は、アプリケーションでの便宜を考慮して、(D3DRS_WRAPn ステート値の 1 つを明示的に使用する代わりに) 定数 D3DRENDERSTATE_WRAPBIAS を定義し、テクスチャ座標セットのゼロから始まる整数値に基づいて、テクスチャ ラッピングを有効にしたり、無効にしたりする。次の例のように、D3DRENDERSTATE_WRAPBIAS 値をテクスチャ座標セットのゼロ始点インデックスに加算して、そのインデックスに対応する D3DRS_WRAPn 値を計算する。

    On Local Error Resume Next

    ' 変数 lIndex のインデックスに対応するテクスチャ座標セットを
    ' 使用するテクスチャに対して、U/V ラッピングを有効にする。
    Call d3dDevice8.SetRenderState( _
            lIndex + D3DRENDERSTATE_WRAPBIAS, _
            D3DWRAPCOORD_0 Or D3DWRAPCOORD_1)

    ' lIndexが 3 の場合、加算の結果の値は、
    ' D3DRENDERSTATE_WRAP3 (131) に等しくなる。
    If Err.Number <> DD_OK Then
       ' エラー処理コード。
    End If

参照

CONST_D3DRENDERSTATETYPE


CONST_D3DWRAPFLAGS

複数のテクスチャ座標セットを使用する際のテクスチャ ラッピング動作を定義する。

Enum CONST_D3DWRAPFLAGS
    D3DWRAP_U      = 1
    D3DWRAPCOORD_0 = 1
    D3DWRAP_V      = 2
    D3DWRAPCOORD_1 = 2
    D3DWRAP_W      = 4
    D3DWRAPCOORD_2 = 4
    D3DWRAPCOORD_3 = 8
End Enum

定数

D3DWRAP_U および D3DWRAPCOORD_0
テクスチャの第一ディメンジョンの方向にラップする。
D3DWRAP_V および D3DWRAPCOORD_1
テクスチャの第二ディメンジョンの方向にラップする。
D3DWRAP_W および D3DWRAPCOORD_2
テクスチャの第三ディメンジョンの方向にラップする。
D3DWRAPCOORD_3
テクスチャの第四ディメンジョンの方向にラップする。

注意

これらのフラグは、CONST_D3DRENDERSTATETYPE 列挙の D3DRS_WRAP0 から D3DRS_WRAP7 までのレンダリング ステートの値を設定するために使われる。

参照

CONST_D3DRENDERSTATETYPE


CONST_D3DZBUFFERTYPE

深度バッファ フォーマットを記述する定数を定義する。

Enum CONST_D3DZBUFFERTYPE
    D3DZB_FALSE = 0
    D3DZB_TRUE  = 1
    D3DZB_USEW  = 2
End Enum

定数

D3DZB_FALSE
深度バッファの使用を無効にする。
D3DZB_TRUE
z バッファの使用を可能にする。
D3DZB_USEW
w バッファの使用を可能にする。

注意

これらのフラグは、CONST_D3DRENDERSTATETYPE 列挙の D3DRS_ZENABLE レンダリング ステートの値を設定するために使われる。

参照

CONST_D3DRENDERSTATETYPE


テクスチャ引数フラグ

デバイスに対応するそれぞれのテクスチャ ステージは 2 つのテクスチャ引数を持つことができ、これらの引数はテクスチャのカラー チャネルまたはアルファ チャネルに影響を与える。

テクスチャ引数を設定および取得するには、それぞれ Direct3DDevice8.SetTextureStageState メソッドと Direct3DDevice8.GetTextureStageState メソッドを呼び出して、CONST_D3DTEXTURESTAGESTATETYPE 列挙の定数 D3DTSS_COLORARG1、D3DTSS_COLORARG2、D3DTSS_ALPHAARG1、または D3DTSS_ALPHAARG2 を指定する。

次に示すフラグ (引数と修正子にまとめられている) を、テクスチャ ステージの色引数およびアルファ引数と共に使用することができる。引数フラグと修正子を組み合わせることはできるが、2 つの引数フラグを組み合わせることはできない。

引数フラグ
D3DTA_CURRENT
テクスチャ引数は前のブレンディング ステージの結果である。最初のテクスチャ ステージ (ステージ ゼロ) では、この引数はデフォルト値の D3DTA_DIFFUSE に相当する。前のブレンディング ステージでバンプマップ テクスチャ (D3DTOP_BUMPENVMAP 処理) が使用されている場合、システムはバンプマップ テクスチャの前のステージからテクスチャを選択するs が現在のテクスチャ ステージを表し、s – 1 にバンプマップ テクスチャが含まれている場合、この引数はテクスチャ ステージ s – 2 によって出力される結果になる。許可は読み書きである。
D3DTA_DIFFUSE
テクスチャ引数は、グーロー シェーディング処理中に頂点の成分から補間して得られたディフューズ色である。頂点がディフューズ色を含まない場合のデフォルト色は &HFFFFFFFF である。許可は読み取り専用である。
D3DTA_SELECTMASK
すべての引数に対応するマスク値。テクスチャ引数の設定には使用しない。
D3DTA_SPECULAR
テクスチャ引数は、グーロー シェーディング処理中に頂点の成分から補間して得られたスペキュラ色である。頂点がスペキュラ色を含まない場合のデフォルト色は &HFFFFFFFF である。許可は読み取り専用である。
D3DTA_TEMP
テンポラリ レジスタの色を選択する。許可は読み書きである。
D3DTA_TEXTURE
テクスチャ引数は、このテクスチャ ステージのテクスチャ カラーである。このブレンディング引数を使用するステージにテクスチャが設定されていない場合、システムはデフォルトでカラー値 Ｒ、G、B およびアルファをそれぞれ 1.0 に設定する。許可は読み取り専用である。
D3DTA_TFACTOR
テクスチャ引数は、前回 D3DRS_TEXTUREFACTOR レンダリング ステート値を使って Direct3DDevice8.SetRenderState を呼び出したときのテクスチャ係数セットである。
修正子フラグ
D3DTA_ALPHAREPLICATE
処理が完了する前に、アルファ情報をすべてのカラー チャネルに複製する。
D3DTA_COMPLEMENT
引数の逆数を取る。たとえば、引数の結果が変数 x で示されているなら、その値は 1.0 - x になる。


柔軟な頂点フォーマット フラグ

柔軟な頂点フォーマット (FVF) は、単一のデータ ストリームにインターリーブされて格納されている頂点のコンテンツを記述するために使われる。FVF コードは、通常、固定機能の頂点処理によって処理されるデータを指定するために使われる。

CONST_D3DFVFFLAGS 列挙で定義されている次のフラグは、頂点フォーマットを記述している。

柔軟な頂点フォーマット (FVF) フラグ
D3DFVF_DIFFUSE
頂点フォーマットがディフューズ色成分を含む。
D3DFVF_NORMAL
頂点フォーマットが頂点法線ベクトルを含む。このフラグを、D3DFVF_XYZRHW フラグと共に使うことはできない。
D3DFVF_PSIZE
頂点フォーマットはポイント サイズで指定されている。このサイズは、トランスフォーム済みでもライティング済みでもない頂点に対してはカメラ空間単位で、またトランスフォーム済みでライティング済みの頂点に対してはデバイス空間単位で表されている。
D3DFVF_SPECULAR
頂点フォーマットがスペキュラ色成分を含む。
D3DFVF_VERTEX )
(D3DFVF_XYZ Or D3DFVF_NORMAL Or D3DFVF_TEX1) を指定した場合と同様。
D3DFVF_XYZ
頂点フォーマットが未トランスフォーム頂点の位置座標を含む。このフラグを、D3DFVF_XYZRHW フラグと共に使うことはできない。
D3DFVF_XYZRHW
頂点フォーマットが、トランスフォームされた頂点の位置座標を含む。このフラグを D3DFVF_XYZ フラグまたは D3DFVF_NORMAL フラグと共に使用することはできない。
D3DFVF_XYZB1 ～ D3DFVF_XYZB5
頂点フォーマットは、位置座標データ、および複数の行列による頂点ブレンディング処理用の加重 (ベータ) 値の対応数を含む。現在、Microsoft® Direct3D® では最大 3 つの加重値および 4 つのブレンディング行列でブレンディングが可能である。
テクスチャ関連 FVF フラグ
D3DFVF_TEX0 ～ D3DFVF_TEX8
この頂点に対応するテクスチャ座標セットの番号。これらのフラグに対する実際の値は連続番号になっていない。テクスチャに関連するその他の FVF フラグについては、「CONST_D3DFVFTEXTUREFORMATS 列挙」を参照すること。
マスク値
D3DFVF_POSITION_MASK
位置座標ビットを抽出するマスク。
D3DFVF_RESERVED0 および D3DFVF_RESERVED2
柔軟な頂点フォーマットの予約ビットを抽出するためのマスク値。使用不可。
D3DFVF_TEXCOUNT_MASK
テクスチャ フラグ ビットを抽出するためのマスク値。
その他
D3DFVF_TEXCOUNT_SHIFT
頂点のテクスチャ座標数を識別する整数値を何ビット分シフトするかを示す数。

参照

頂点フォーマットについて、ジオメトリ ブレンディング


FOURCC コード

Microsoft® Direct3D® および Direct3DX ユーティリティ ライブラリでは、4 文字の長さの特殊なコードが使用される。これらのコードは、4 文字コードまたは FOURCC と呼ばれ、ビットマップ イメージ、サウンド、ビデオなどのマルチメディア データを格納するファイルのファイル ヘッダーに保存される。FOURCC は、マルチメディア データを生成するために使用されたソフトウェア テクノロジを示す。また、暗に、データ自体のフォーマットも表す。

Direct3D アプリケーションは、イメージの色やフォーマットの変換に FOURCC を使用する。

FOURCC は、個々のマルチメディア ソフトウェア テクノロジのベンダーによって、Microsoft に登録される。次の一覧は、一般的な FOURCC の一部を示している。

FOURCC | 会社名 | テクノロジ名
AUR2 | AuraVision Corporation | AuraVision Aura 2:YUV 422
AURA | AuraVision Corporation | AuraVision Aura 1:YUV 411
CHAM | Winnov, Inc. | MM_WINNOV_CAVIARA_CHAMPAGNE
CVID | Supermac | Cinepak by Supermac
CYUV | Creative Labs, Inc. | Creative Labs YUV
DXT1 | Microsoft Corporation | DirectX Texture Compression Format 1
DXT2 | Microsoft Corporation | DirectX Texture Compression Format 2
DXT3 | Microsoft Corporation | DirectX Texture Compression Format 3
DXT4 | Microsoft Corporation | DirectX Texture Compression Format 4
DXT5 | Microsoft Corporation | DirectX Texture Compression Format 5
FVF1 | Iterated Systems, Inc. | Fractal Video Frame
IF09 | Intel Corporation | Intel Intermediate YUV9
IV31 | Intel Corporation | Indeo 3.1
JPEG | Microsoft Corporation | Still Image JPEG DIB
MJPG | Microsoft Corporation | Motion JPEG DIB Format
MRLE | Microsoft Corporation | Run Length Encoding
MSVC | Microsoft Corporation | Video 1
PHMO | IBM Corporation | Photomotion
RT21 | Intel Corporation | Indeo 2.1
ULTI | IBM Corporation | Ultimotion
V422 | Vitec Multimedia | 24-bit YUV 4:2:2
V655 | Vitec Multimedia | 16-bit YUV 4:2:2
VDCT | Vitec Multimedia | Video Maker Pro DIB
VIDS | Vitec Multimedia | YUV 4:2:2 CCIR 601 for V422
YU92 | Intel Corporation | YUV
YUV8 | Winnov, Inc. | MM_WINNOV_CAVIAR_YUV8
YUV9 | Intel Corporation | YUV9
YUYV | Canopus, Co., Ltd. | BI_YUYV, Canopus
ZPEG | Metheus | Video Zipper


エラー コード

エラーは負の値で表され、組み合わされることはない。次の一覧は、Microsoft® Direct3D® のメソッドによって返される可能性のある値を示している。各メソッドが返す可能性のある値の一覧については、各メソッドの説明を参照すること。

D3D_OK
エラーは発生していない。
D3DERR_CANNOTTATTRSORT
最適化テクニックとして属性のソート (D3DXMESHOPT_ATTRSORT) はサポートされていない。
D3DERR_CONFLICTINGRENDERSTATE
現在設定されているレンダリング ステートを同時に使用することはできない。
D3DERR_CONFLICTINGTEXTUREFILTER
現在のテクスチャ フィルタを同時に使用することはできない。
D3DERR_CONFLICTINGTEXTUREPALETTE
現在のテクスチャを同時に使用することはできない。一般に、マルチテクスチャ デバイスにおいて、同時に有効になっているパレット化テクスチャが同じパレットの共有を要求すると発生する。
D3DERR_DEVICELOST
デバイスが失われていて、現時点では復元できないため、レンダリングは不可能である。
D3DERR_DEVICENOTRESET
デバイスをリセットできない。
D3DERR_DRIVERINTERNALERROR
内部ドライバ エラー。
D3DERR_INVALIDCALL
メソッドの呼び出しが無効である。たとえば、メソッドのパラメータに無効な値が設定されている場合などである。
D3DERR_INVALIDDEVICE
要求されたデバイスのタイプが無効である。
D3DERR_MOREDATA
指定されたバッファ サイズに保持できる以上のデータが存在する。
D3DERR_NOTAVAILABLE
このデバイスは、照会されたテクニックをサポートしていない。
D3DERR_NOTFOUND
要求された項目が見つからなかった。
D3DERR_OUTOFVIDEOMEMORY
Direct3D が処理を行うのに十分なディスプレイ メモリがない。
D3DERR_TOOMANYOPERATIONS
デバイスがサポートしている数より多くのテクスチャ フィルタリング処理を、アプリケーションが要求している。
D3DERR_UNSUPPORTEDALPHAARG
アルファ チャネルに対して指定されているテクスチャ ブレンディング引数を、デバイスがサポートしていない。
D3DERR_UNSUPPORTEDALPHAOPERATION
アルファ チャネルに対して指定されているテクスチャ ブレンディング処理を、デバイスがサポートしていない。
D3DERR_UNSUPPORTEDCOLORARG
カラー値に対して指定されているテクスチャ ブレンディング引数を、デバイスがサポートしていない。
D3DERR_UNSUPPORTEDCOLOROPERATION
カラー値に対して指定されているテクスチャ ブレンディング処理を、デバイスがサポートしていない。
D3DERR_UNSUPPORTEDFACTORVALUE
指定されたテクスチャ係数値をデバイスがサポートしていない。
D3DERR_UNSUPPORTEDTEXTUREFILTER
指定されたテクスチャ フィルタをデバイスがサポートしていない。
D3DERR_WRONGTEXTUREFORMAT
テクスチャ サーフェスのピクセル フォーマットが無効である。
E_FAIL
Direct3D サブシステム内で原因不明のエラーが発生した。
E_INVALIDARG
無効なパラメータが戻ってくる関数に渡された。
E_INVALIDCALL
メソッドの呼び出しが無効である。たとえば、メソッドのパラメータに無効な値が設定されている場合などである。
E_OUTOFMEMORY
Direct3D が呼び出しを完了するために十分なメモリを割り当てることができなかった。


Direct3DX Visual Basic リファレンス

ここでは、Direct3DX ユーティリティ ライブラリが提供する API 要素のリファレンス情報を記述する。リファレンス情報は、次のカテゴリに分類される。

  • クラス
  • 関数
  • 型
  • 列挙
  • エラー コード


クラス

ここでは、Direct3DX ユーティリティ ライブラリが提供するクラスのリファレンス情報を記述する。Direct3DX ユーティリティ ライブラリでは次のクラスが使用される。

  • D3DX8
  • D3DXBaseMesh
  • D3DXBuffer
  • D3DXFont
  • D3DXMesh
  • D3DXPMesh
  • D3DXRenderToSurface
  • D3DXSkinMesh
  • D3DXSPMesh
  • D3DXSprite


D3DX8

アプリケーションは D3DX8 クラスのメソッドを使用し、テクスチャの作成、メッシュの操作、形状の描画、シェーダのアセンブルといった複雑なタスクを単純化する。

D3DX8 クラスのインスタンスは、オブジェクト変数を宣言し、D3DX8 の新規インスタンスにその変数を設定することによって取得する (次のコード参照)。

Dim d3dx As D3DX8
Set d3dx = New D3DX8

D3DX8 クラスのメソッドは、以下のグループにまとめることができる。

メッシュ | BoxBoundProbe
 | CleanMesh
 | ComputeBoundingBox
 | ComputeBoundingBoxFromMesh
 | ComputeBoundingSphere
 | ComputeBoundingSphereFromMesh
 | ComputeNormals
 | CreateBuffer
 | CreateMesh
 | CreateMeshFVF
 | CreatePolygon
 | CreateSkinMesh
 | CreateSkinMeshFromMesh
 | CreateSkinMeshFVF
 | CreateSPMesh
 | DeclaratorFromFVF
 | FVFFromDeclarator
 | GeneratePMesh
 | Intersect
 | LoadPMeshFromFile
 | LoadSkinMeshFromXof
 | LoadMeshFromX
 | LoadMeshFromXof
 | SaveMeshToX
 | SavePMeshToFile
 | SimplifyMesh
 | SphereBoundProbe
 | TesselateMesh
 | ValidMesh
その他 | BufferGetBoneCombo
 | BufferGetBoneComboBoneIds
 | BufferGetBoneName
 | BufferGetData
 | BufferGetMaterial
 | BufferGetTextureName
 | BufferSetData
 | CreateFont
 | CreateRenderToSurface
 | CreateSprite
 | GetErrorString
 | GetFVFVertexSize
シェーダ | AssembleShader
 | AssembleShaderFromFile
形状 | CreateBox
 | CreateCylinder
 | CreateSphere
 | CreateTeapot
 | CreateText
 | CreateTorus
テクスチャ | CheckCubeTextureRequirements
 | CheckTextureRequirements
 | CheckVolumeTextureRequirements
 | CreateCubeTexture
 | CreateCubeTextureFromFile
 | CreateCubeTextureFromFileEx
 | CreateCubeTextureFromFileInMemory
 | CreateCubeTextureFromFileInMemoryEx
 | CreateTexture
 | CreateTextureFromFile
 | CreateTextureFromFileEx
 | CreateTextureFromFileInMemory
 | CreateTextureFromFileInMemoryEx
 | CreateTextureFromResource
 | CreateTextureFromResourceEx
 | CreateVolumeTexture
 | FilterCubeTexture
 | FilterTexture
 | FilterVolumeTexture
 | LoadSurfaceFromFile
 | LoadSurfaceFromFileInMemory
 | LoadSurfaceFromMemory
 | LoadSurfaceFromResource
 | LoadSurfaceFromSurface
 | LoadVolumeFromMemory
 | LoadVolumeFromVolume


D3DX8.AssembleShader

頂点シェーダのソースがメモリ内にある場合に、ピクセル シェーダまたは頂点シェーダの ASCII 記述をバイナリ形式にアセンブルする。

object.AssembleShader( _
    SrcData As Any, _
    Flags As Long, _
    Constants As D3DXBuffer) As D3DXBuffer

指定項目

object
D3DX8 オブジェクトを表すオブジェクト式。
SrcData
シェーダをアセンブルする元となるソース コード。
Flags
アセンブリ オプションを指定する CONST_D3DXASM 型のメンバの組み合わせ。
Constants
定数宣言を格納する D3DXBuffer オブジェクト。これらの定数は、頂点シェーダ宣言子フラグメントとして返される。アプリケーションは、このバッファの内容を定数宣言に挿入する必要がある。ピクセル シェーダの場合、定数宣言はアセンブルされたシェーダに含まれるため、このパラメータは意味を成さない。このパラメータが NULL の場合は無視される。

戻り値

コンパイル済みのオブジェクト コードを格納する D3DXBuffer オブジェクトを返す。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DXERR_INVALIDDATA
E_OUTOFMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。


D3DX8.AssembleShaderFromFile

ピクセル シェーダまたは頂点シェーダの ASCII 記述をバイナリ形式にアセンブルする。

object.AssembleShaderFromFile( _
    SrcFile As String, _
    Flags As Long, _
    ErrLog As String, _
    Constants As D3DXBuffer) As D3DXBuffer

指定項目

object
D3DX8 オブジェクトを表すオブジェクト式。
SrcFile
ソース ファイル名。
Flags
アセンブリ オプションを指定する CONST_D3DXASM 型のメンバの組み合わせ。
ErrLog
ASCII エラー メッセージを保持する。
Constants
定数宣言を格納する D3DXBuffer オブジェクト。これらの定数は、頂点シェーダ宣言子フラグメントとして返される。アプリケーションは、このバッファの内容を定数宣言に挿入する必要がある。ピクセル シェーダの場合、定数宣言はアセンブルされたシェーダに含まれるため、このパラメータは意味を成さない。このパラメータが NULL の場合は無視される。

戻り値

コンパイル済みのオブジェクト コードを格納する D3DXBuffer オブジェクトを返す。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DXERR_INVALIDDATA
E_OUTOFMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。


D3DX8.BoxBoundProbe

レイがボックスの境界ボックスのボリュームに当たるかどうかを判定する。

object.BoxBoundProbe( _
    MinVert As D3DVECTOR, _
    MaxVert As D3DVECTOR, _
    RayPosition As D3DVECTOR, _
    Raydirection As D3DVECTOR) As Boolean

指定項目

object
D3DX8 オブジェクトを表すオブジェクト式。
MinVert
境界ボックスの左下隅を記述する、D3DVECTOR 型。「注意」を参照すること。
MaxVert
境界ボックスの右上隅を記述する、D3DXVECTOR 型。「注意」を参照すること。
RayPosition
レイの始点座標を指定する D3DXVECTOR 型。
Raydirection
レイの方向を指定する D3DXVECTOR 型。

戻り値

レイがボックスの境界ボックスのボリュームに当たる場合は、TRUE を返す。それ以外の場合は FALSE を返す。

注意

D3DX8.BoxBoundProbe は、レイがボックスのサーフェスだけではなく、ボックスの境界ボックスのボリュームに当たるかどうかを判定する。

D3DX8.BoxBoundProbe に渡される D3DXVECTOR の値は、xmin、xmax、ymin、ymax、zmin、zmax である。したがって、境界ボックスの角の定義は次のようになる。

xmax, ymax, zmax
xmax, ymax, zmin
xmax, ymin, zmax
xmax, ymin, zmin
xmin, ymax, zmax
xmin, ymax, zmin
xmin, ymin, zmax
xmin, ymin, zmin

境界ボックスの深度は、z 方向が zmax - zmin、y 方向が ymax - ymin、そして x 方向が xmax - xmin である。たとえば、最小ベクトルが min (-1, -1, -1)、最大ベクトルが (1, 1, 1) の場合、境界ボックスの定義は次のようになる。

 1,  1,  1
 1,  1, -1
 1, -1,  1
 1, -1, -1
-1,  1,  1
-1,  1, -1
-1, -1,  1
-1, -1, -1

エラー コード

失敗した場合はエラーが発生し、Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。


D3DX8.BufferGetBoneCombo

バッファからボーンの組み合わせを取得する。

object.BufferGetBoneCombo( _
    BoneComboBuffer As D3DXBuffer, _
    Index As Long, _
    BoneCombo As D3DXBONECOMBINATION)

指定項目

object
D3DX8 オブジェクトを表すオブジェクト式。
BoneComboBuffer
ボーン組み合わせデータを格納しているバッファである、D3DXBuffer オブジェクト。
Index
バッファへのインデックスを指定するインデックス値。
BoneCombo
Index で指定したボーンのボーン組み合わせデータを格納する D3DXBONECOMBINATION 型。

エラー コード

失敗した場合はエラーが発生し、Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

参照

D3DX8.LoadSkinMeshFromXof、D3DXSkinMesh.ConvertToBlendedMesh


D3DX8.BufferGetBoneComboBoneIds

ボーンの組み合わせバッファからボーンの ID を取得する。

object.BufferGetBoneComboBoneIds( _

    BoneComboBuffer As D3DXBuffer, _
    Index As Long, _
    PaletteSize As Long, _
    BoneIds As Any)

指定項目

object
D3DX8 オブジェクトを表すオブジェクト式。
BoneComboBuffer
ボーン データを格納しているバッファである、D3DXBuffer オブジェクト。
Index
バッファへのインデックスを指定するインデックス値。
PaletteSize
ボーンの組み合わせが持つことのできる行列の最大数。
BoneIds
単一の描画呼び出しの中で描画できるボーンそれぞれを識別する値の配列の、最初の要素。配列の長さは可変であり、D3DXSkinMesh.ConvertToIndexedBlendedMesh の可変長のボーンの組み合わせに適応できる。

エラー コード

失敗した場合はエラーが発生し、Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

参照

D3DXSkinMesh.GetMaxVertexInfluences、D3DXSkinMesh.GetNumBoneInfluences


D3DX8.BufferGetBoneName

バッファからボーンの名前を取得する。

object.BufferGetBoneName( _
    BoneNameBuffer As D3DXBuffer, _
    Index As Long) As String

指定項目

object
D3DX8 オブジェクトを表すオブジェクト式。
BoneNameBuffer
ボーン データを格納しているバッファである、D3DXBuffer オブジェクト。
Index
バッファへのインデックスを指定するインデックス値。

戻り値

ボーンの名前を識別する String。

エラー コード

失敗した場合はエラーが発生し、Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。


D3DX8.BufferGetData

バッファからデータを取得する。

object.BufferGetData( _
    Buffer As D3DXBuffer, _
    Index As Long, _
    TypeSize As Long, _
    TypeCount As Long, _
    Data As Any)

指定項目

object
D3DX8 オブジェクトを表すオブジェクト式。
Buffer
取得するデータを格納しているバッファである、D3DXBuffer オブジェクト。
Index
バッファへのインデックスを指定するインデックス値。
TypeSize
バッファから取得するデータ型のサイズ (バイト単位)。
TypeCount
バッファから取得する要素の数。
Data
メソッドが戻った後、取得されたバッファ データを保持するオブジェクト。

エラー コード

失敗した場合はエラーが発生し、Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。


D3DX8.BufferGetMaterial

バッファからマテリアルを取得する。

object.BufferGetMaterial( _
    MaterialBuffer As D3DXBuffer, _
    Index As Long, _
    Mat As D3DMATERIAL8)

指定項目

object
D3DX8 オブジェクトを表すオブジェクト式。
MaterialBuffer
取得するマテリアルを格納するバッファである D3DXBuffer オブジェクト。
Index
バッファのインデックスを指定するインデックス値。
Mat
照会したバッファから取得されたマテリアルを表す、D3DMATERIAL8 オブジェクト。

エラー コード

失敗した場合はエラーが発生し、Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。


D3DX8.BufferGetTextureName

バッファからテクスチャの名前を取得する。

object.BufferGetTextureName( _
    MaterialBuffer As D3DXBuffer, _
    Index As Long) As String

指定項目

object
D3DX8 オブジェクトを表すオブジェクト式。
MaterialBuffer
取得するマテリアルを格納するバッファである D3DXBuffer オブジェクト。
Index
バッファのインデックスを指定するインデックス値。

戻り値

照会したバッファに格納されているテクスチャ名を識別する、返された文字列。

エラー コード

失敗した場合はエラーが発生し、Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。


D3DX8.BufferSetData

バッファにデータを設定する。

object.BufferSetData( _
    Buffer As D3DXBuffer, _
    Index As Long, _
    TypeSize As Long, _
    TypeCount As Long, _
    Data As Any)

指定項目

object
D3DX8 オブジェクトを表すオブジェクト式。
Buffer
データと共にロードするバッファであるD3DXBuffer オブジェクト。
Index
バッファへのインデックスを指定するインデックス値。
TypeSize
バッファにロードするデータ型のサイズ (バイト単位)。
TypeCount
バッファにロードする要素の数。
Data
バッファにロードするデータを保持するオブジェクト。

エラー コード

失敗した場合はエラーが発生し、Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。


D3DX8.CheckCubeTextureRequirements

キューブ テクスチャ作成パラメータを確認する。

object.CheckCubeTextureRequirements( _
    Device As Direct3DDevice8, _
    Size As Long, _
    NumMipLevels As Long, _
    Usage As Long, _
    Format As CONST_D3DFORMAT, _
    Pool As CONST_D3DPOOL)

指定項目

object
D3DX8 オブジェクトを表すオブジェクト式。
Device
キューブ テクスチャに関連付けられているデバイスを表す Direct3DDevice8 オブジェクト。
Size
要求された幅と高さ (ピクセル単位) または ByVal 0。訂正後のサイズを返す。
NumMipLevels
要求されたミップマップ レベルの数、または ByVal 0。訂正後のミップマップ レベルの数を返す。
Usage
0 または CONST_D3DUSAGEFLAGS 列挙の D3DUSAGE_RENDERTARGET メンバ。D3DUSAGE_RENDERTARGET を指定すると、そのサーフェスはレンダリング ターゲットとして使用されることを示す。リソースは、SetRenderTarget メソッドの NewRenderTarget パラメータに渡すことができる。D3DUSAGE_RENDERTARGET を指定する場合、アプリケーションは Direct3D8.CheckDeviceFormat を呼び出して、デバイスがこれらの処理をサポートしていることを確認する必要がある。
Format
CONST_D3DFORMAT 列挙のメンバ。要求されるピクセル フォーマットを指定する。訂正後のフォーマットを返す。
Pool
キューブ テクスチャの配置先となるメモリ クラスを記述する、CONST_D3DPOOL 列挙のメンバ。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DERR_NOTAVAILABLE

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

キューブ テクスチャは、サーフェスのコレクションである点でほかのサーフェスとは異なる。キューブ テクスチャを指定して SetRenderTarget を呼び出すには、Direct3DCubeTexture8.GetCubeMapSurface を使用して個々の面を選択し、結果サーフェスを SetRenderTarget に渡す必要がある。

このメソッドに対するパラメータが無効な場合、この関数は訂正後のパラメータを返す。


D3DX8.CheckTextureRequirements

テクスチャ作成パラメータを確認する。

object.CheckTextureRequirements( _
    Device As Direct3DDevice8, _
    Width As Long, _
    Height As Long, _
    NumMipLevels As Long, _
    Usage As Long, _
    Format As CONST_D3DFORMAT, _
    Pool As CONST_D3DPOOL)

指定項目

object
D3DX8 オブジェクトを表すオブジェクト式。
Device
キューブ テクスチャに関連付けられているデバイスを表す Direct3DDevice8 オブジェクト。
Width
要求された幅 (ピクセル単位)、または ByVal 0。訂正後のサイズを返す。
Height
要求された高さ (ピクセル単位) または ByVal 0。訂正後のサイズを返す。
NumMipLevels
要求されたミップマップ レベルの数、または ByVal 0。訂正後のミップマップ レベルの数を返す。
Usage
0 または CONST_D3DUSAGEFLAGS 列挙の D3DUSAGE_RENDERTARGET メンバ。D3DUSAGE_RENDERTARGET を指定すると、そのサーフェスはレンダリング ターゲットとして使用されることを示す。リソースは、SetRenderTarget メソッドの NewRenderTarget パラメータに渡すことができる。D3DUSAGE_RENDERTARGET を指定する場合、アプリケーションは Direct3D8.CheckDeviceFormat を呼び出して、デバイスがこれらの処理をサポートしていることを確認する必要がある。
Format
CONST_D3DFORMAT 列挙のメンバ。要求されるピクセル フォーマットを指定する。訂正後のフォーマットを返す。
Pool
テクスチャの配置先となるメモリ クラスを記述する、CONST_D3DPOOL 列挙のメンバ。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DERR_NOTAVAILABLE

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

このメソッドに対するパラメータが無効な場合、この関数は訂正後のパラメータを返す。


D3DX8.CheckVolumeTextureRequirements

ボリューム テクスチャ作成パラメータを確認する。

object.CheckVolumeTextureRequirements( _
    Device As Direct3DDevice8, _
    Width As Long, _
    Height As Long, _
    Depth As Long, _
    NumMipLevels As Long, _
    Usage As Long, _
    PixelFormat CONST_D3DFORMAT, _
    Pool As CONST_D3DPOOL)

指定項目

object
D3DX8 オブジェクトを表すオブジェクト式。
Device
ボリューム テクスチャに関連付けられたデバイスを表す、Direct3DDevice8 オブジェクト。
Width
要求された幅 (ピクセル単位)、または ByVal 0。訂正後のサイズを返す。
Height
要求された高さ (ピクセル単位) または ByVal 0。訂正後のサイズを返す。
Depth
要求された深度 (ピクセル単位)、または ByVal 0。訂正後のサイズを返す。
NumMipLevels
要求されたミップマップ レベルの数、または ByVal 0。訂正後のミップマップ レベルの数を返す。
Usage
現時点では未使用なので 0 を設定しておく。
PixelFormat
CONST_D3DFORMAT 列挙のメンバ。要求されるピクセル フォーマットを指定する。訂正後のフォーマットを返す。
Pool
ボリューム テクスチャの配置先となるメモリ クラスを記述する、CONST_D3DPOOL 列挙のメンバ。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DERR_NOTAVAILABLE

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

この関数のパラメータが無効の場合、この関数は訂正後のパラメータを返す。


D3DX8.CleanMesh

単純化の準備として、メッシュのクリーニングを行う。

object.CleanMesh( _
    MeshIn As D3DXMesh, _
    Adjacency As Any) As D3DXMesh

指定項目

object
D3DX8 オブジェクトを表すオブジェクト式。
MeshIn
クリーニングするメッシュを表す、D3DXMesh オブジェクト。
Adjacency
クリーニングするメッシュに含まれる各面の 3 つの隣接面を指定する、1 面あたりの 3 つの Long 値の配列の最初の要素。クリーニングの必要がない場合は、渡したメッシュと同じメッシュが返される。

戻り値

返されたクリーニング済みメッシュを表す D3DXMesh オブジェクト。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
E_OUTOFMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

このメソッドは、2 つの三角形ファンが同じ頂点を共有している場合に、頂点を追加することによってメッシュのクリーニングを行う。

次のサンプル コードは、D3DXBuffer オブジェクトを使用して隣接性情報を渡す方法を示している。

Dim d3dxbAdjacency As D3DXBuffer
Dim mesh As D3DXMesh

' このコードでは d3dxbAdjacency およびメッシュが正しく
' 初期化されていると仮定している。
Call D3DX8.CleanMesh(d3dxm, ByVal d3dxbAdjacency.GetBufferPointer)


D3DX8.ComputeBoundingBox

境界ボックスを算出する。

object.ComputeBoundingBox( _
    PointsFVF As Any, _
    NumVertices As Long, _
    FVF As Long, _
    MinArray As D3DVECTOR, _
    MaxArray As D3DVECTOR)

指定項目

object
D3DX8 オブジェクトを表すオブジェクト式。
PointsFVF
算出する境界ボックスの頂点データを格納するバッファ。
NumVertices
頂点の数。
FVF
頂点フォーマットを記述する柔軟な頂点フォーマット フラグの組み合わせ。
MinArray
境界ボックスの左下隅を記述する、D3DVECTOR 型。「注意」を参照すること。
MaxArray
境界ボックスの右上隅を記述する、D3DVECTOR 型。「注意」を参照すること。

エラー コード

失敗した場合はエラーが発生し、Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

ComputeBoundingBox が返す D3DVECTOR の値は、xmin、xmax、ymin、ymax、zmin、zmax である。したがって、境界ボックスの角の定義は次のようになる。

xmax, ymax, zmax
xmax, ymax, zmin
xmax, ymin, zmax
xmax, ymin, zmin
xmin, ymax, zmax
xmin, ymax, zmin
xmin, ymin, zmax
xmin, ymin, zmin

境界ボックスの深度は、z 方向が zmax - zmin、y 方向が ymax - ymin、そして x 方向が xmax - xmin である。たとえば、最小ベクトルが min (-1, -1, -1)、最大ベクトルが (1, 1, 1) の場合、境界ボックスの定義は次のようになる。

 1,  1,  1
 1,  1, -1
 1, -1,  1
 1, -1, -1
-1,  1,  1
-1,  1, -1
-1, -1,  1
-1, -1, -1

参照

D3DX8.ComputeBoundingBoxFromMesh


D3DX8.ComputeBoundingBoxFromMesh

メッシュから境界ボックスを算出する。

object.ComputeBoundingBoxFromMesh( _
    MeshIn As D3DXMesh, _
    MinArray As D3DVECTOR, _
    MaxArray As D3DVECTOR)

指定項目

object
D3DX8 オブジェクトを表すオブジェクト式。
MeshIn
入力メッシュを表す D3DXMesh オブジェクト。
MinArray
境界ボックスの左下隅を記述する、D3DVECTOR 型。「注意」を参照すること。
MaxArray
境界ボックスの右上隅を記述する、D3DVECTOR 型。「注意」を参照すること。

エラー コード

失敗した場合はエラーが発生し、Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

ComputeBoundingBoxFromMesh が返す D3DVECTOR の値は、xmin、xmax、ymin、ymax、zmin、zmax である。したがって、境界ボックスの角の定義は次のようになる。

xmax, ymax, zmax
xmax, ymax, zmin
xmax, ymin, zmax
xmax, ymin, zmin
xmin, ymax, zmax
xmin, ymax, zmin
xmin, ymin, zmax
xmin, ymin, zmin

境界ボックスの深度は、z 方向が zmax - zmin、y 方向が ymax - ymin、そして x 方向が xmax - xmin である。たとえば、最小ベクトルが min (-1, -1, -1)、最大ベクトルが (1, 1, 1) の場合、境界ボックスの定義は次のようになる。

 1,  1,  1
 1,  1, -1
 1, -1,  1
 1, -1, -1
-1,  1,  1
-1,  1, -1
-1, -1,  1
-1, -1, -1

参照

D3DX8.ComputeBoundingBox


D3DX8.ComputeBoundingSphere

境界球を算出する。

object.ComputeBoundingSphere( _
    PointsFVF As Any, _
    NumVertices As Long, _
    FVF As Long, _
    Center As D3DVECTOR, _
    RadiusArray As Single)

指定項目

object
D3DX8 オブジェクトを表すオブジェクト式。
PointsFVF
算出する境界球の頂点データを格納するバッファ。
NumVertices
頂点の数。
FVF
頂点フォーマットを記述する柔軟な頂点フォーマット フラグの組み合わせ。
Center
境界球の座標の中心を定義する、D3DVECTOR 型。
RadiusArray
境界球の半径。

エラー コード

失敗した場合はエラーが発生し、Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。


D3DX8.ComputeBoundingSphereFromMesh

メッシュから境界球を算出する。

object.ComputeBoundingSphereFromMesh( _
    MeshIn As D3DXMesh, _
    Center As D3DVECTOR, _
    RadiusArray As Single)

指定項目

object
D3DX8 オブジェクトを表すオブジェクト式。
MeshIn
入力メッシュを表す D3DXMesh オブジェクト。
Center
境界球の座標の中心を定義する、D3DVECTOR 型。
RadiusArray
境界球の半径。

エラー コード

失敗した場合はエラーが発生し、Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。


D3DX8.ComputeNormals

メッシュに含まれる角頂点の法線を算出する。

object.ComputeNormals( _
    Mesh As D3DXBaseMesh)

指定項目

object
D3DX8 オブジェクトを表すオブジェクト式。
Mesh
正規化されたメッシュ オブジェクトを表す、D3DXBaseMesh オブジェクト。

エラー コード

失敗した場合はエラーが発生し、Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注 入力メッシュの FVF に D3DFVF_NORMAL フラグが指定されている必要がある。

頂点の法線は、その頂点を共有するすべての面の法線を平均することにより、生成される。


D3DX8.CreateBox

左手座標系を使用し、軸に沿ったボックスを含むメッシュを作成する。

object.CreateBox( _
    D3DDevice As Direct3DDevice8, _
    Width As Single, _
    Height As Single, _
    Depth As Single, _
    RetAdjacency As D3DXBuffer)As D3DXMesh

指定項目

object
D3DX8 オブジェクトを表すオブジェクト式。
D3DDevice
作成されたボックス メッシュに関連付けられたデバイスを表す、Direct3DDevice8 オブジェクト。
Width
x 軸方向のボックスの幅。
Height
y 軸方向のボックスの高さ。
Depth
z 軸方向のボックスの深度。
RetAdjacency
D3DXBuffer オブジェクト。メソッドが返ると、このパラメータには、メッシュに含まれる各面の 3 つの隣接面を指定する、1 面あたりの 3 つの Long 値の配列が入力される。

戻り値

出力ボックスを表す D3DXMesh オブジェクト。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DXERR_INVALIDDATA
E_OUTOFMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。


D3DX8.CreateBuffer

バッファ オブジェクトを作成する。

object.CreateBuffer( _
    NumBytes As Long) As D3DXBuffer

指定項目

object
D3DX8 オブジェクトを表すオブジェクト式。
NumBytes
作成するバッファのサイズ (バイト単位)。

戻り値

作成されたバッファを表す D3DXBuffer オブジェクト。

エラー コード

失敗した場合はエラーが発生し、Err.Number に E_OUTOFMEMORY が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。


D3DX8.CreateCubeTexture

必要に応じて呼び出しパラメータを調整し、空のキューブ テクスチャを作成する。

object.CreateCubeTexture( _
    Device As Direct3DDevice8, _
    Size As Long, _
    MipLevels As Long, _
    Usage As Long, _
    Format As CONST_D3DFORMAT, _
    Pool As CONST_D3DPOOL) As Direct3DCubeTexture8

指定項目

object
D3DX8 オブジェクトを表すオブジェクト式。
Device
キューブ テクスチャに関連付けられたデバイスを表す、Direct3DDevice8 オブジェクト。
Size
キューブ テクスチャの幅と高さ (ピクセル単位)。キューブ テクスチャが 8 × 8 ピクセルのキューブである場合、このパラメータの値は 8 である。この値は 0 以外である必要がある。
MipLevels
要求されたミップ レベルの数。この値が 0 または CONST_D3DXENUM 列挙で定義される D3DX_DEFAULT の場合は、完全なミップマップ チェーンが作成される。
Usage
0 または CONST_D3DUSAGEFLAGS 列挙の D3DUSAGE_RENDERTARGET メンバ。D3DUSAGE_RENDERTARGET を指定すると、そのサーフェスはレンダリング ターゲットとして使用されることを示す。リソースは、SetRenderTarget メソッドの NewRenderTarget パラメータに渡すことができる。D3DUSAGE_RENDERTARGET を指定する場合、アプリケーションは Direct3D8.CheckDeviceFormat を呼び出して、デバイスがこれらの処理をサポートしていることを確認する必要がある。
Format
キューブ テクスチャに対して要求されたピクセル フォーマットを記述する CONST_D3DFORMAT 列挙。返されるキューブ テクスチャのフォーマットは Format で指定されたフォーマットと異なる場合がある。アプリケーションは、返されたキューブ テクスチャのフォーマットを確認する必要がある。
Pool
キューブ テクスチャの配置先となるメモリ クラスを記述する、CONST_D3DPOOL 列挙のメンバ。

戻り値

作成されたキューブ テクスチャを表す、Direct3DCubeTexture8 オブジェクト。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DERR_NOTAVAILABLE
D3DXERR_INVALIDDATA
D3DERR_OUTOFVIDEOMEMORY
E_OUTOFMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

キューブ テクスチャは、サーフェスのコレクションである点でほかのサーフェスとは異なる。キューブ テクスチャを指定して SetRenderTarget を呼び出すには、Direct3DCubeTexture8.GetCubeMapSurface を使用して個々の面を選択し、結果サーフェスを SetRenderTarget に渡す必要がある。

D3DX8.CreateCubeTexture は、内部で D3DX8.CheckCubeTextureRequirements を使用して呼び出しパラメータを調整する。したがって、Direct3Ddevice8.CreateCubeTexture の呼び出しが失敗する場合でも、D3DX8.CreateCubeTexture の呼び出しは成功することが多い。


D3DX8.CreateCubeTextureFromFile

ファイルを元にしてキューブ テクスチャを作成する。

object.CreateCubeTextureFromFile( _
    Device As Direct3DDevice8, _
    SrcFile As String) As Direct3DCubeTexture8

パラメータ

object
D3DX8 オブジェクトを表すオブジェクト式。
Device
キューブ テクスチャに関連付けられたデバイスを表す、Direct3DDevice8 オブジェクト。
SrcFile
キューブ テクスチャの作成に使用するファイルを指定する文字列。「注意」を参照すること。

戻り値

作成されたキューブ テクスチャを表す、Direct3DCubeTexture8 オブジェクト。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DERR_NOTAVAILABLE
D3DERR_OUTOFVIDEOMEMORY
D3DXERR_INVALIDDATA
E_OUTOFMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

この関数を使用して作成したリソースは、CONST_D3DPOOL 列挙型の D3DPOOL_MANAGED メンバで示されるメモリ クラスに配置される。

CreateCubeTextureFromFile は、DirectDrawSurface (DDS) ファイル フォーマットを使用する。DXTex ツールによって、ほかのファイル フォーマットからキューブ マップを生成し、それを DDS ファイル フォーマットで保存することができる。


D3DX8.CreateCubeTextureFromFileEx

ファイルを元にしてキューブ テクスチャを作成する。これは、D3DX8.CreateCubeTextureFromFile よりも高度なメソッドである。

object.CreateCubeTextureFromFileEx( _
    Device As Direct3DDevice8, _
    SrcFile As String, _
    TextureSize As Long, _
    MipLevels As Long, _
    Usage As Long, _
    Format As CONST_D3DFORMAT, _
    Pool As CONST_D3DPOOL, _
    Filter As Long, _
    MipFilter As Long, _
    ColorKey As Long, _
    SrcInfo As Any, _
    Palette As Any) As Direct3DCubeTexture8

パラメータ

object
D3DX8 オブジェクトを表すオブジェクト式。
Device
キューブ テクスチャに関連付けられたデバイスを表す、Direct3DDevice8 オブジェクト。
SrcFile
キューブ テクスチャの作成に使用するファイルを指定する文字列。「注意」を参照すること。
TextureSize
キューブ テクスチャの幅と高さ (ピクセル単位)。キューブ テクスチャが 8 × 8 ピクセルのキューブである場合、このパラメータの値は 8 である。この値は 0 以外である必要がある。この値が 0 または D3DX_DEFAULT の場合、ディメンジョンはファイルから取得される。
MipLevels
要求されたミップ レベルの数。この値が 0 または CONST_D3DXENUM 列挙で定義される D3DX_DEFAULT の場合は、完全なミップマップ チェーンが作成される。
Usage
0 または CONST_D3DUSAGEFLAGS 列挙の D3DUSAGE_RENDERTARGET メンバ。D3DUSAGE_RENDERTARGET を指定すると、そのサーフェスはレンダリング ターゲットとして使用されることを示す。リソースは、SetRenderTarget メソッドの NewRenderTarget パラメータに渡すことができる。D3DUSAGE_RENDERTARGET を指定する場合、アプリケーションは Direct3D8.CheckDeviceFormat を呼び出して、デバイスがこれらの処理をサポートしていることを確認する必要がある。
Format
キューブ テクスチャに対して要求されたピクセル フォーマットを記述する CONST_D3DFORMAT 列挙。返されるキューブ テクスチャのフォーマットは Format で指定されたフォーマットと異なる場合がある。アプリケーションは、返されたキューブ テクスチャのフォーマットを確認する必要がある。Format が D3DFMT_UNKNOWN の場合、フォーマットはファイルから取得される。
Pool
キューブ テクスチャの配置先となるメモリ クラスを記述する、CONST_D3DPOOL 列挙のメンバ。
Filter
イメージをフィルタリングする方法を制御する、CONST_D3DXENUM 列挙で定義される 1 つ以上のフィルタ フラグの組み合わせ。このパラメータに D3DX_DEFAULT を指定することは、D3DX_FILTER_DITHER OR D3DX_FILTER_TRIANGLE を指定することと等しい。
MipFilter
イメージをフィルタリングする方法を制御する、CONST_D3DXENUM 列挙で定義される 1 つ以上のミップ フィルタ フラグの組み合わせ。このパラメータに D3DX_DEFAULT を指定することは、D3DX_FILTER_BOX を指定することと等しい。
ColorKey
透明となる値。カラーキーを無効にする場合は 0 を指定する。ソース イメージのフォーマットとは関係なく、これは常に 32 ビットの ARGB カラーである。アルファが有意であり、通常はカラーキーを不透明にする場合は FF を指定する。したがって、不透明な黒の場合、値は &HFF000000 となる。
SrcInfo
ソース イメージ ファイル内のデータの記述を格納する D3DXIMAGE_INFO 構造体、または ByVal 0。
Palette
格納する 256 色パレットを表すオブジェクト、または Nothing。

戻り値

作成されたキューブ テクスチャを表す、Direct3DCubeTexture8 オブジェクト。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DERR_NOTAVAILABLE
D3DERR_OUTOFVIDEOMEMORY
D3DXERR_INVALIDDATA
E_OUTOFMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

キューブ テクスチャは、サーフェスのコレクションである点でほかのサーフェスとは異なる。キューブ テクスチャを指定して SetRenderTarget を呼び出すには、Direct3DCubeTexture8.GetCubeMapSurface を使用して個々の面を選択し、結果サーフェスを SetRenderTarget に渡す必要がある。

CreateCubeTextureFromFileEx は、DirectDrawSurface (DDS) ファイル フォーマットを使用する。DXTex ツールによって、ほかのファイル フォーマットからキューブ マップを生成し、それを DDS ファイル フォーマットで保存することができる。


D3DX8.CreateCubeTextureFromFileInMemory

メモリ内のファイルからキューブ テクスチャを作成する。

object.CreateCubeTextureFromFileInMemory( _
    Device As Direct3DDevice8, _
    SrcData As Any, _
    LengthInBytes As Long) As Direct3DCubeTexture8

パラメータ

object
D3DX8 オブジェクトを表すオブジェクト式。
Device
キューブ テクスチャに関連付けられたデバイスを表す、Direct3DDevice8 オブジェクト。
SrcData
キューブ テクスチャの作成に使用するメモリ内のファイル。「注意」を参照すること。
LengthInBytes
メモリ内のファイルのサイズ (バイト単位)。

戻り値

作成されたキューブ テクスチャを表す、Direct3DCubeTexture8 オブジェクト。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DERR_NOTAVAILABLE
D3DERR_OUTOFVIDEOMEMORY
D3DXERR_INVALIDDATA
E_OUTOFMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

この関数を使用して作成したリソースは、CONST_D3DPOOL 列挙型の D3DPOOL_MANAGED メンバで示されるメモリ クラスに配置される。

このメソッドは、アプリケーション定義のリソース (未加工データ) である、RT_RCDATA として格納されたイメージ ファイルをロードするために使用するように設計されている。それ以外の目的に使用すると、このメソッドは失敗する。

CreateCubeTextureFromFileInMemory は、DirectDrawSurface (DDS) ファイル フォーマットを使用する。DXTex ツールによって、ほかのファイル フォーマットからキューブ マップを生成し、それを DDS ファイル フォーマットで保存することができる。


D3DX8.CreateCubeTextureFromFileInMemoryEx

メモリ内のファイルからキューブ テクスチャを作成する。これは、D3DX8.CreateCubeTextureFromFileInMemory よりも高度なメソッドである。

object.CreateCubeTextureFromFileInMemoryEx( _
    Device As Direct3DDevice8, _
    SrcData As Any, _
    LengthInBytes As Long, _
    TextureSize As Long, _
    MipLevels As Long, _
    Usage As Long, _
    Format As CONST_D3DFORMAT, _
    Pool As CONST_D3DPOOL, _
    Filter As Long, _
    MipFilter As Long, _
    ColorKey As Long, _
    SrcInfo As Any, _
    Palette As Any) As Direct3DCubeTexture8

パラメータ

object
D3DX8 オブジェクトを表すオブジェクト式。
Device
キューブ テクスチャに関連付けられたデバイスを表す、Direct3DDevice8 オブジェクト。
SrcData
キューブ テクスチャの作成に使用するメモリ内のファイル。「注意」を参照すること。
LengthInBytes
メモリ内のファイルのサイズ (バイト単位)。
TextureSize
ファイルのサイズ (バイト単位)。
MipLevels
要求されたミップ レベルの数。この値が 0 または CONST_D3DXENUM 列挙で定義される D3DX_DEFAULT の場合は、完全なミップマップ チェーンが作成される。
Usage
0 または CONST_D3DUSAGEFLAGS 列挙の D3DUSAGE_RENDERTARGET メンバ。D3DUSAGE_RENDERTARGET を指定すると、そのサーフェスはレンダリング ターゲットとして使用されることを示す。リソースは、SetRenderTarget メソッドの NewRenderTarget パラメータに渡すことができる。D3DUSAGE_RENDERTARGET を指定する場合、アプリケーションは Direct3D8.CheckDeviceFormat を呼び出して、デバイスがこれらの処理をサポートしていることを確認する必要がある。
Format
キューブ テクスチャに対して要求されたピクセル フォーマットを記述する CONST_D3DFORMAT 列挙。返されるキューブ テクスチャのフォーマットは Format で指定されたフォーマットと異なる場合がある。アプリケーションは、返されたキューブ テクスチャのフォーマットを確認する必要がある。この値が D3DFMT_UNKNOWN の場合、フォーマットはファイルから取得される。
Pool
キューブ テクスチャの配置先となるメモリ クラスを記述する、CONST_D3DPOOL 列挙のメンバ。
Filter
イメージをフィルタリングする方法を制御する、CONST_D3DXENUM 列挙で定義される 1 つ以上のフィルタ フラグの組み合わせ。このパラメータに D3DX_DEFAULT を指定することは、D3DX_FILTER_DITHER OR D3DX_FILTER_TRIANGLE を指定することと等しい。
MipFilter
イメージをフィルタリングする方法を制御する、CONST_D3DXENUM 列挙で定義される 1 つ以上のミップ フィルタ フラグの組み合わせ。このパラメータに D3DX_DEFAULT を指定することは、D3DX_FILTER_BOX を指定することと等しい。
ColorKey
透明となる値。カラーキーを無効にする場合は 0 を指定する。ソース イメージのフォーマットとは関係なく、これは常に 32 ビットの ARGB カラーである。アルファが有意であり、通常はカラーキーを不透明にする場合は FF を指定する。したがって、不透明な黒の場合、値は &HFF000000 となる。
SrcInfo
ソース イメージ ファイル内のデータの記述を格納する D3DXIMAGE_INFO 構造体、または ByVal 0。
Palette
格納する 256 色パレットを表すオブジェクト、または Nothing。

戻り値

作成されたキューブ テクスチャを表す、Direct3DCubeTexture8 オブジェクト。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DERR_NOTAVAILABLE
D3DERR_OUTOFVIDEOMEMORY
D3DXERR_INVALIDDATA
E_OUTOFMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

キューブ テクスチャは、サーフェスのコレクションである点でほかのサーフェスとは異なる。キューブ テクスチャを指定して SetRenderTarget を呼び出すには、Direct3DCubeTexture8.GetCubeMapSurface を使用して個々の面を選択し、結果サーフェスを SetRenderTarget に渡す必要がある。

このメソッドは、アプリケーション定義のリソース (未加工データ) である、RT_RCDATA として格納されたイメージ ファイルをロードするために使用するように設計されている。それ以外の目的に使用すると、このメソッドは失敗する。

CreateCubeTextureFromFileInMemoryEx は、DirectDrawSurface (DDS) ファイル フォーマットを使用する。DXTex ツールによって、ほかのファイル フォーマットからキューブ マップを生成し、それを DDS ファイル フォーマットで保存することができる。


D3DX8.CreateCylinder

左手座標系を使用し、円柱のメッシュを作成する。

object.CreateCylinder( _
    Device As Direct3DDevice8, _
    Radius1 As Single, _
    Radius2 As Single
    Length As Single, _
    Slices As Long, _
    Stacks As Long, _
    RetAdjacency As D3DXBuffer) As D3DXMesh

指定項目

object
D3DX8 オブジェクトを表すオブジェクト式。
Device
作成された円柱メッシュに関連付けられたデバイスを表す、Direct3DDevice8 オブジェクト。
Radius1
z 軸の負の側の面の半径。値は 0.0f 以上である必要がある。
Radius2
z 軸の正の側の面の半径。値は 0.0f 以上である必要がある。
Length
z 軸方向の円柱の長さ。
Slices
主軸を回転軸としたスライスの数。
Stacks
主軸に沿ったスタック数。
RetAdjacency
D3DXBuffer オブジェクト。メソッドが返ると、このパラメータには、メッシュに含まれる各面の 3 つの隣接面を指定する、1 面あたりの 3 つの Long 値の配列が入力される。

戻り値

出力ボックスを表す D3DXMesh オブジェクト。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DXERR_INVALIDDATA
E_OUTOFMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

キューブ テクスチャは、サーフェスのコレクションである点でほかのサーフェスとは異なる。キューブ テクスチャを指定して SetRenderTarget を呼び出すには、Direct3DCubeTexture8.GetCubeMapSurface を使用して個々の面を選択し、結果サーフェスを SetRenderTarget に渡す必要がある。


D3DX8.CreateFont

デバイスとフォント用のフォント オブジェクトを作成する。

object.CreateFont( _
    Device As Direct3DDevice8, _
    hFont As Long) As D3DXFont

指定項目

object
D3DX8 オブジェクトを表すオブジェクト式。
Device
フォント オブジェクトに関連付けられたデバイスを表す、Direct3DDevice8 オブジェクト。
hFont
フォント オブジェクトへのハンドル。

戻り値

作成されたフォント オブジェクトを表す、D3DXFont オブジェクト。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
E_OUTOFMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。


D3DX8.CreateMesh

宣言子を使用してメッシュ オブジェクトを作成する。

object.CreateMesh( _
    NumFaces As Long, _
    NumVertices As Long, _
    Options As Long, _
    Declaration As Any, _
    Device As Direct3DDevice8) As D3DXMesh

指定項目

object
D3DX8 オブジェクトを表すオブジェクト式。
NumFaces
メッシュの面の数。このパラメータは 1 以上でなければならない。
NumVertices
メッシュの頂点の数。このパラメータは 1 以上でなければならない。
Options
メッシュに対するオプションを指定する、CONST_D3DXMESH 列挙で定義される 1 つ以上のフラグの組み合わせ。
Declaration
返されたメッシュの頂点フォーマットを記述する宣言子。このパラメータは FVF を直接マップする必要がある。
Device
メッシュに関連付けられるデバイスである Direct3DDevice8 オブジェクト。

戻り値

作成されたメッシュを表す D3DXMesh オブジェクト。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
E_OUTOFMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

参照

D3DX8.DeclaratorFromFVF


D3DX8.CreateMeshFVF

柔軟な頂点フォーマット (FVF) コードを使用してメッシュ オブジェクトを作成する。

object.CreateMeshFVF( _
    NumFaces As Long, _
    NumVertices As Long, _
    Options As Long, _
    FVF As Long, _
    Device As Direct3DDevice8) As D3DXMesh

指定項目

object
D3DX8 オブジェクトを表すオブジェクト式。
NumFaces
メッシュの面の数。このパラメータは 1 以上でなければならない。
NumVertices
メッシュの頂点の数。このパラメータは 1 以上でなければならない。
Options
メッシュに対するオプションを指定する、CONST_D3DXMESH 列挙で定義される 1 つ以上のフラグの組み合わせ。
FVF
メッシュの頂点フォーマットを記述する、柔軟な頂点フォーマット フラグの組み合わせ。
Device
メッシュに関連付けられるデバイスである Direct3DDevice8 オブジェクト。

戻り値

作成されたメッシュを表す D3DXMesh オブジェクト。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
E_OUTOFMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

参照

D3DX8.FVFFromDeclarator


D3DX8.CreatePolygon

左手座標系を使用し、n 面のポリゴンを含むメッシュを作成する。

object.CreatePolygon( _
    D3DDevice As Direct3DDevice8, _
    Length As Single, _
    Sides As Long, _
    RetAdjacency As D3DXBuffer) As D3DXMesh

指定項目

object
D3DX8 オブジェクトを表すオブジェクト式。
D3DDevice
作成されたポリゴン メッシュに関連付けられたデバイスを表す、Direct3DDevice8 オブジェクト。
Length
各面の長さ。
Sides
ポリゴンの面数。値は 3 以上である必要がある。
RetAdjacency
D3DXBuffer オブジェクト。メソッドが返ると、このパラメータには、メッシュに含まれる各面の 3 つの隣接面を指定する、1 面あたりの 3 つの Long 値の配列が入力される。

戻り値

作成されたポリゴン メッシュを表す D3DXMesh オブジェクト。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DXERR_INVALIDDATA
E_OUTOFMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

作成されるポリゴンの中心は原点となる。


D3DX8.CreateRenderToSurface

レンダリング サーフェスを作成する。

object.CreateRenderToSurface( _
    D3DDevice As Direct3DDevice8, _
    Width As Long, _
    Height As Long, _
    Format As CONST_D3DFORMAT, _
    DepthStencil As Long, _
    DepthStencilFormat As CONST_D3DFORMAT) As D3DXRenderToSurface

指定項目

object
D3DX8 オブジェクトを表すオブジェクト式。
D3DDevice
レンダリング サーフェスに関連付けられる Direct3DDevice8 オブジェクト。
Width
レンダリング サーフェスの幅 (ピクセル単位)。
Height
レンダリング サーフェスの高さ (ピクセル単位)。
Format
レンダリング ターゲットのフォーマットを記述する、CONST_D3DFORMAT 列挙のメンバ。
DepthStencil
TRUE の場合、レンダリング サーフェスは深度ステンシル サーフェスをサポートする。サポートしない場合、このメンバは FALSE に設定される。
DepthStencilFormat
DepthStencil が TRUE に設定される場合、このパラメータは、レンダリング サーフェスの深度ステンシル フォーマットを記述する CONST_D3DFORMAT 列挙のメンバである。

戻り値

作成されたポリゴン メッシュを表す D3DXRenderToSurface オブジェクト。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
E_OUTOFMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

作成されるポリゴンの中心は原点となる。


D3DX8.CreateSkinMesh

宣言子を使用して空のスキン メッシュ オブジェクトを作成する。

object.CreateSkinMesh( _
    NumFaces As Long, _
    NumVertices As Long, _
    NumBones As Long, _
    Options As Long, _
    Declaration As Any, _
    D3DDevice As Direct3DDevice8) As D3DXSkinMesh

指定項目

object
D3DX8 オブジェクトを表すオブジェクト式。
NumFaces
スキン メッシュの面の数。
NumVertices
スキン メッシュの頂点の数。
NumBones
スキン メッシュのボーンの数。
Options
スキン メッシュに対するオプションを指定する、CONST_D3DXMESH 列挙で定義される 1 つ以上のフラグの組み合わせ。
Declaration
スキン メッシュの頂点フォーマットを記述する宣言子を表す Long 値。
D3DDevice
スキン メッシュに関連付けられるデバイス オブジェクトである Direct3DDevice8 オブジェクト。

戻り値

作成されたスキン メッシュを表す D3DXSkinMesh オブジェクト。

エラー コード

失敗した場合はエラーが発生し、Err.Number に E_OUTOFMEMORY が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

このメソッドで返される空のスキン メッシュ オブジェクトにデータを代入するには、D3DXSkinMesh.SetBoneInfluence を使用する。


D3DX8.CreateSkinMeshFromMesh

別のメッシュからスキン メッシュを作成する。

object.CreateSkinMeshFromMesh( _
    Mesh As D3DXMesh, _
    NumBones As Long) As D3DXSkinMesh

指定項目

object
D3DX8 オブジェクトを表すオブジェクト式。
Mesh
スキン メッシュ作成の元となるメッシュである D3DXMesh オブジェクト。
NumBones
スキン メッシュのボーンの数。

戻り値

作成されたスキン メッシュ オブジェクトを表す D3DXSkinMesh オブジェクト。

エラー コード

失敗した場合はエラーが発生し、Err.Number に E_OUTOFMEMORY が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。


D3DX8.CreateSkinMeshFVF

柔軟な頂点フォーマット (FVF) コードを使用して空のスキン メッシュ オブジェクトを作成する。

object.CreateSkinMeshFVF( _
    NumFaces As Long, _
    NumVertices As Long, _
    NumBones As Long, _
    Options As Long, _
    FVF As Long, _
    D3DDevice As Direct3DDevice8) As D3DXSkinMesh

指定項目

object
D3DX8 オブジェクトを表すオブジェクト式。
NumFaces
スキン メッシュの面の数。
NumVertices
スキン メッシュの頂点の数。
NumBones
スキン メッシュのボーンの数。
Options
スキン メッシュに対するオプションを指定する、CONST_D3DXMESH 列挙型の 1 つ以上のメンバの組み合わせ。
FVF
返されたスキン メッシュの頂点フォーマットを記述する、柔軟な頂点フォーマット フラグの組み合わせ。
D3DDevice
スキン メッシュに関連付けられるデバイス オブジェクトである Direct3DDevice8 オブジェクト。

戻り値

作成されたスキン メッシュ オブジェクトを表す D3DXSkinMesh オブジェクト。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
E_OUTOFMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

このメソッドで返される空のスキン メッシュ オブジェクトにデータを代入するには、D3DXSkinMesh.SetBoneInfluence を使用する。


D3DX8.CreateSphere

左手座標系を使用し、球を含むメッシュを作成する。

object.CreateSphere( _
    D3DDevice As Direct3DDevice8, _
    Radius As Single, _
    Slices As Long, _
    Stacks As Long, _
    RetAdjacency As D3DXBuffer) As D3DXMesh

指定項目

object
D3DX8 オブジェクトを表すオブジェクト式。
D3DDevice
作成された球メッシュに関連付けられた Direct3DDevice8 オブジェクト。
Radius
球の半径。この値は 0 以上である必要がある。
Slices
主軸を回転軸としたスライスの数。
Stacks
主軸に沿ったスタック数。
RetAdjacency
メッシュに含まれる各面の 3 つの隣接面を指定する、1 面あたりの 3 つの Long 値の配列を格納する D3DXBuffer オブジェクト。

戻り値

作成された球を表す D3DXMesh オブジェクト。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DXERR_INVALIDDATA
E_OUTOFMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

作成される球は、中心が原点となり、軸は z 軸方向となる。


D3DX8.CreateSPMesh

単純化メッシュを作成する。

object.CreateSPMesh( _
    Mesh As D3DXMesh, _
    Adjacency As Any, _
    VertexAttributeWeights As Any, _
    VertexWeights As Any) As D3DXSPMesh

指定項目

object
D3DX8 オブジェクトを表すオブジェクト式。
Mesh
単純化を行うメッシュを表す、D3DXMesh オブジェクト。
Adjacency
作成された単純化メッシュに含まれる各面の 3 つの隣接面を指定する、1 面あたりの 3 つの Long 値の配列の最初の要素。
VertexAttributeWeights
各頂点の成分に対する加重を格納する D3DXATTRIBUTEWEIGHTS 型。このパラメータを ByVal 0 に設定すると、デフォルトの型が使用される。
VertexWeights
頂点加重の配列の最初の要素。頂点加重が大きいほど、単純化されにくいことに注意する。

戻り値

作成された単純化メッシュを表す、D3DXSPMesh オブジェクト。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DXERR_CANNOTATTRSORT
D3DERR_INVALIDCALL
E_OUTOFMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

単純化メッシュは、メッシュを単純化して、三角形と面の数を減らすために使用する。

VertexAttributeWeights を ByVal 0 に設定した場合、値はデフォルトの D3DXATTRIBUTEWEIGHTS 型に従って割り当てられる。

Dim AttribruteWeights As D3DXATTRIBUTEWEIGHTS
With _
.position = 1
.Boundary = 1
.Normal = 1
.diffuse = 0
.specular = 0
.Tex(7) = 0
End With

大部分のアプリケーションでは、このデフォルトの型を使用する。デフォルトではジオメトリと法線の調整のみが考慮される。その他のメンバ フィールドを修正する必要があるのは、特別な場合のみである。

次のサンプル コードは、D3DXBuffer オブジェクトを使用して隣接性情報を渡す方法を示している。

Dim Mesh As D3DXMesh
Dim D3DXbAdjacency As D3DXBuffer
Dim VAttWeights As Any
Dim VWeights As Any

' このコードでは、すべての引数が
' 正しく初期化されていると仮定している。
Call D3DX8.CreateSPMesh(Mesh, ByVal D3DXbAdjacency.GetBufferPointer, VAttWeights, Vweights )


D3DX8.CreateSprite

スプライトを作成する。

object.CreateSprite( _
    D3DDevice As Direct3DDevice8) As D3DXSprite

指定項目

object
D3DX8 オブジェクトを表すオブジェクト式。
D3DDevice
スプライトに関連付けられるデバイスを表す Direct3DDevice8 オブジェクト。

戻り値

作成されたスプライトを表す D3DXSprite オブジェクト。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
E_OUTOFMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。


D3DX8.CreateTeapot

ティーポットを作成する。

object.CreateTeapot( _
    D3DDevice As Direct3DDevice8, _
    RetAdjacency As D3DXBuffer) As D3DXMesh

指定項目

object
D3DX8 オブジェクトを表すオブジェクト式。
D3DDevice
テクスチャに関連付けられているデバイスを表す Direct3DDevice8 オブジェクト。
RetAdjacency
D3DXBuffer オブジェクト。メソッドが返ると、このパラメータには、メッシュに含まれる各面の 3 つの隣接面を指定する、1 面あたりの 3 つの Long 値の配列が入力される。

戻り値

作成されたティーポットを表す D3DXMesh オブジェクト。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DXERR_INVALIDDATA
E_OUTOFMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。


D3DX8.CreateText

デバイス コンテキストに関連付けられているフォントを使用し、指定したテキストを含むメッシュを作成する。

object.CreateText( _
    D3DDevice As Direct3DDevice8, _
    HDC As Long, _
    Text As String, _
    Deviation As Single, _
    Extrusion As Single, _
    RetMesh As D3DXMesh, _
    GlyphMetrics As Any)

指定項目

object
D3DX8 オブジェクトを表すオブジェクト式。
D3DDevice
作成されたテキストに関連付けられる Direct3DDevice8 オブジェクト。
HDC
出力用のフォントを格納しているデバイスのコンテキスト。デバイスのコンテキストによって選択されるフォントは、TrueType フォントでなければならない。
Text
生成するテキストを指定する文字列。
Deviation
TRUE フォント アウトラインからの最大コード偏差。
Extrusion
z 軸の負の方向に押し出されるテキストの量。
RetMesh
出力形状である D3DXMesh オブジェクト。
GlyphMetrics
グリフ メトリック データを受け取る GLYPHMETRICSFLOAT 型の配列の最初の要素。配列内の各 GLYPHMETRICSFLOAT 型には、文字列内の対応するグリフの、配置と向きに関する情報が格納される。配列内の要素の数は、文字列の文字数と等しくなければならない。各型の始点は、文字列全体に対して相対的ではなく、その文字セルに対して相対的である。境界ボックス全体の演算を行うには、文字列をトラバースする間グリフごとに増分を追加する。

グリフ サイズを考慮する必要がない場合は、GlyphMetrics に ByVal 0 を渡すことができる。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DXERR_INVALIDDATA
E_OUTOFMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。


D3DX8.CreateTexture

必要に応じて呼び出しパラメータを調整し、空のテクスチャを作成する。

object.CreateTexture( _
    Device As Direct3DDevice8, _
    Width As Long, _
    Height As Long, _
    MipLevels As Long, _
    Usage As Long, _
    PixelFormat As CONST_D3DFORMAT, _
    Pool As CONST_D3DPOOL) As Direct3DTexture8

指定項目

object
D3DX8 オブジェクトを表すオブジェクト式。
Device
テクスチャに関連付けられているデバイスを表す Direct3DDevice8 オブジェクト。
Width
テクスチャの最上位レベルの幅 (ピクセル単位)。レベルが下のピクセル ディメンジョンは 1 つ上のレベルのピクセル ディメンジョンを (単純に) 1/2 した値である。それぞれの大きさは、1 ピクセルのサイズに収められる。したがって、2 で除算した結果が 0 (ゼロ) の場合は、代わりに 1 が使用される。この値が 0 に設定されている場合、値 1 が使用される。D3DX_DEFAULT を使用することもできる。「注意」を参照すること。
Height
テクスチャの最上位レベルの高さ (ピクセル単位)。レベルが下のピクセル ディメンジョンは 1 つ上のレベルのピクセル ディメンジョンを (単純に) 1/2 した値である。それぞれの大きさは、1 ピクセルのサイズに収められる。したがって、2 で除算した結果が 0 (ゼロ) の場合は、代わりに 1 が使用される。この値が 0 に設定されている場合、値 1 が使用される。D3DX_DEFAULT を使用することもできる。「注意」を参照すること。
MipLevels
テクスチャのレベルの数。ゼロを指定すると、1 × 1 ピクセルまでのすべてのテクスチャ サブレベルが生成される。
Usage
0 または CONST_D3DUSAGEFLAGS 列挙のD3DUSAGE_RENDERTARGET メンバ。D3DUSAGE_RENDERTARGET を指定すると、そのサーフェスはレンダリング ターゲットとして使用されることを示す。リソースは、SetRenderTarget メソッドの NewRenderTarget パラメータに渡すことができる。D3DUSAGE_RENDERTARGET を指定する場合、アプリケーションは Direct3D8.CheckDeviceFormat を呼び出して、デバイスがこれらの処理をサポートしていることを確認する必要がある。
PixelFormat
テクスチャに対して要求されたピクセル フォーマットを記述する CONST_D3DFORMAT 列挙のメンバ。返されるテクスチャのフォーマットは PixelFormat で指定されたフォーマットと異なる場合がある。アプリケーションは、返されたテクスチャのフォーマットを確認する必要がある。
Pool
テクスチャの配置先となるメモリ クラスを記述する、CONST_D3DPOOL 列挙のメンバ。

戻り値

作成されたテクスチャを表す Direct3DTexture8 オブジェクト。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DERR_NOTAVAILABLE
D3DERR_OUTOFVIDEOMEMORY
E_OUTOFMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

Height と Width の両方のパラメータに D3DX_DEFAULT が設定されている場合、どちらも値 256 が使用される。片方のパラメータだけに D3DX_DEFAULT が設定されている場合、テクスチャは正方形になり、もう一方のサイズ パラメータが高さと幅の両方を指定する。

D3DX8.CreateTexture は、内部で D3DX8.CheckTextureRequirements を使用して呼び出しパラメータを調整する。したがって、Direct3Ddevice8.CreateTexture の呼び出しが失敗する場合でも、D3DX8.CreateTexture の呼び出しは成功することが多い。


D3DX8.CreateTextureFromFile

ファイルを元にしてテクスチャを作成する。

object.CreateTextureFromFile( _
    Device As Direct3DDevice8, _
    SrcFile As String) As Direct3DTexture8

指定項目

object
D3DX8 オブジェクトを表すオブジェクト式。
Device
テクスチャに関連付けられているデバイスを表す Direct3DDevice8 オブジェクト。
SrcFile
テクスチャの作成に使用するファイルを指定する String 値。

戻り値

作成されたテクスチャを表す Direct3DTexture8 オブジェクト。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DERR_NOTAVAILABLE
D3DERR_OUTOFVIDEOMEMORY
D3DXERR_INVALIDDATA
E_OUTOFMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

ミップマップされたテクスチャの各レベルには、ロードされたテクスチャが自動的に格納される。

ミップマップされたテクスチャにイメージをロードするとき、デバイスによっては、1x1 のイメージに変換できず、関数が失敗することがある。このような場合は、イメージを手動でロードする必要がある。

この関数を使用して作成したリソースは、CONST_D3DPOOL 列挙型の D3DPOOL_MANAGED メンバで示されるメモリ クラスに配置される。


D3DX8.CreateTextureFromFileEx

ファイルを元にしてテクスチャを作成する。これは、D3DX8.CreateTextureFromFile よりも高度なメソッドである。

object.CreateTextureFromFileEx( _
    Device As Direct3DDevice8, _
    SrcFile As String, _
    Width As Long, _
    Height As Long, _
    MipLevels As Long, _
    Usage As Long, _
    Format As CONST_D3DFORMAT, _
    Pool As CONST_D3DPOOL, _
    Filter As Long, _
    MipFilter As Long, _
    ColorKey As Long, _
    SrcInfo As Any _
    Palette As Any) As Direct3DTexture8

指定項目

object
D3DX8 オブジェクトを表すオブジェクト式。
Device
テクスチャに関連付けられているデバイスを表す Direct3DDevice8 オブジェクト。
SrcFile
テクスチャの作成に使用するファイルを指定する String 値。
Width
幅 (ピクセル単位)。この値が 0、または CONST_D3DXENUM 列挙で定義される D3DX_DEFAULT の場合、サイズはファイルから取得される。
Height
高さ (ピクセル単位)。この値が 0 または CONST_D3DXENUM 列挙で定義される D3DX_DEFAULT の場合、サイズはファイルから取得される。
MipLevels
要求されたミップ レベルの数。この値が 0 または CONST_D3DXENUM 列挙で定義される D3DX_DEFAULT の場合は、完全なミップマップ チェーンが作成される。
Usage
0 または CONST_D3DUSAGEFLAGS 列挙の D3DUSAGE_RENDERTARGET メンバ。D3DUSAGE_RENDERTARGET を指定すると、そのサーフェスはレンダリング ターゲットとして使用されることを示す。リソースは、SetRenderTarget メソッドの NewRenderTarget パラメータに渡すことができる。D3DUSAGE_RENDERTARGET を指定する場合、アプリケーションは Direct3D8.CheckDeviceFormat を呼び出して、デバイスがこれらの処理をサポートしていることを確認する必要がある。
Format
テクスチャに対して要求されたピクセル フォーマットを記述する CONST_D3DFORMAT 列挙のメンバ。返されるテクスチャのフォーマットは Format で指定されたフォーマットと異なる場合がある。アプリケーションは、返されたテクスチャのフォーマットを確認する必要がある。Format が D3DFMT_UNKNOWN の場合、フォーマットはファイルから取得される。
Pool
テクスチャの配置先となるメモリ クラスを記述する、CONST_D3DPOOL 列挙のメンバ。
Filter
イメージをフィルタリングする方法を制御する、CONST_D3DXENUM 列挙で定義される 1 つ以上のフィルタ フラグの組み合わせ。このパラメータに D3DX_DEFAULT を指定することは、D3DX_FILTER_DITHER OR D3DX_FILTER_TRIANGLE を指定することと等しい。
MipFilter
イメージをフィルタリングする方法を制御する、CONST_D3DXENUM 列挙で定義される 1 つ以上のミップ フィルタ フラグの組み合わせ。このパラメータに D3DX_DEFAULT を指定することは、D3DX_FILTER_BOX を指定することと等しい。
ColorKey
透明となる値。カラーキーを無効にする場合は 0 を指定する。ソース イメージのフォーマットとは関係なく、これは常に 32 ビットの ARGB カラーである。アルファが有意であり、通常はカラーキーを不透明にする場合は FF を指定する。したがって、不透明な黒の場合、値は &HFF000000 となる。
SrcInfo
ソース イメージ ファイル内のデータの記述を格納する D3DXIMAGE_INFO 構造体、または ByVal 0。
Palette
格納する 256 PALETTEENTRY 型の配列の最初の要素、または ByVal 0。「注意」を参照すること。

戻り値

作成されたテクスチャを表す Direct3DTexture8 オブジェクト。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DERR_NOTAVAILABLE
D3DERR_OUTOFVIDEOMEMORY
D3DXERR_INVALIDDATA
E_OUTOFMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

ミップマップされたテクスチャの各レベルには、ロードされたテクスチャが自動的に格納される。

ミップマップされたテクスチャにイメージをロードするとき、デバイスによっては、1x1 のイメージに変換できず、関数が失敗することがある。このような場合は、イメージを手動でロードする必要がある。

PALETTEENTRY の詳細については、Microsoft Platform Software Development Kit (SDK) を参照すること。Microsoft DirectX® 8.0 の時点で、PALETTEENTRY 構造体の peFlags メンバは、Platform SDK に説明されているようには機能しない。peFlags メンバは現在、8 ビットのパレット化されたフォーマット用のアルファ チャネルである。


D3DX8.CreateTextureFromFileInMemory

メモリ内のファイルからテクスチャを作成する。

object.CreateTextureFromFileInMemory( _
    Device As Direct3DDevice8, _
    SrcData As Any, _
    LengthInBytes As Long) As Direct3DTexture8

指定項目

object
D3DX8 オブジェクトを表すオブジェクト式。
Device
テクスチャに関連付けられているデバイスを表す Direct3DDevice8 オブジェクト。
SrcData
テクスチャの作成に使用するメモリ内のファイル。
LengthInBytes
メモリ内のファイルのサイズ (バイト単位)。

戻り値

作成されたテクスチャを表す Direct3DTexture8 オブジェクト。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DERR_NOTAVAILABLE
D3DERR_OUTOFVIDEOMEMORY
D3DXERR_INVALIDDATA
E_OUTOFMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

この関数を使用して作成したリソースは、CONST_D3DPOOL 列挙型の D3DPOOL_MANAGED メンバで示されるメモリ クラスに配置される。

このメソッドは、アプリケーション定義のリソース (未加工データ) である、RT_RCDATA として格納されたイメージ ファイルをロードするために使用するように設計されている。それ以外の目的に使用すると、このメソッドは失敗する。


D3DX8.CreateTextureFromFileInMemoryEx

メモリ内のファイルからテクスチャを作成する。これは、D3DX8.CreateTextureFromFileInMemory よりも高度なメソッドである。

object.CreateTextureFromFileInMemoryEx( _
    Device As Direct3DDevice8, _
    SrcData As Any, _
    LengthInBytes As Long, _
    Width As Long, _
    Height As Long, _
    MipLevels As Long, _
    Usage As Long, _
    Format As CONST_D3DFORMAT, _
    Pool As CONST_D3DPOOL, _
    Filter As Long, _
    MipFilter As Long, _
    ColorKey As Long, _
    SrcInfo As Any, _
    Palette As Any) As Direct3DTexture8

指定項目

object
D3DX8 オブジェクトを表すオブジェクト式。
Device
テクスチャに関連付けられているデバイスを表す Direct3DDevice8 オブジェクト。
SrcData
テクスチャの作成に使用するメモリ内のファイル。
LengthInBytes
メモリ内のファイルのサイズ (バイト単位)。
Width
幅 (ピクセル単位)。この値が 0 または CONST_D3DXENUM 列挙で定義される D3DX_DEFAULT の場合、サイズはファイルから取得される。
Height
高さ (ピクセル単位)。この値が 0、または CONST_D3DXENUM 列挙で定義される D3DX_DEFAULT の場合、サイズはファイルから取得される。
MipLevels
要求されたミップ レベルの数。この値が 0 または CONST_D3DXENUM 列挙で定義される D3DX_DEFAULT の場合は、完全なミップマップ チェーンが作成される。
Usage
0 または CONST_D3DUSAGEFLAGS 列挙の D3DUSAGE_RENDERTARGET メンバ。D3DUSAGE_RENDERTARGET を指定すると、そのサーフェスはレンダリング ターゲットとして使用されることを示す。リソースは、SetRenderTarget メソッドの NewRenderTarget パラメータに渡すことができる。D3DUSAGE_RENDERTARGET を指定する場合、アプリケーションは Direct3D8.CheckDeviceFormat を呼び出して、デバイスがこれらの処理をサポートしていることを確認する必要がある。
Format
テクスチャに対して要求されたピクセル フォーマットを記述する CONST_D3DFORMAT 列挙のメンバ。返されるテクスチャのフォーマットは Format で指定されたフォーマットと異なる場合がある。アプリケーションは、返されたテクスチャのフォーマットを確認する必要がある。Format が D3DFMT_UNKNOWN の場合、フォーマットはファイルから取得される。
Pool
テクスチャの配置先となるメモリ クラスを記述する、CONST_D3DPOOL 列挙のメンバ。
Filter
イメージをフィルタリングする方法を制御する、CONST_D3DXENUM 列挙で定義される 1 つ以上のフィルタ フラグの組み合わせ。このパラメータに D3DX_DEFAULT を指定することは、D3DX_FILTER_DITHER OR D3DX_FILTER_TRIANGLE を指定することと等しい。
MipFilter
イメージをフィルタリングする方法を制御する、CONST_D3DXENUM 列挙で定義される 1 つ以上のミップ フィルタ フラグの組み合わせ。このパラメータに D3DX_DEFAULT を指定することは、D3DX_FILTER_BOX を指定することと等しい。
ColorKey
透明となる値。カラーキーを無効にする場合は 0 を指定する。ソース イメージのフォーマットとは関係なく、これは常に 32 ビットの ARGB カラーである。アルファが有意であり、通常はカラーキーを不透明にする場合は FF を指定する。したがって、不透明な黒の場合、値は &HFF000000 となる。
SrcInfo
ソース イメージ ファイル内のデータの記述を格納する D3DXIMAGE_INFO 構造体、または ByVal 0。
Palette
格納する 256 PALETTEENTRY 型の配列の最初の要素、または ByVal 0。「注意」を参照すること。

戻り値

作成されたテクスチャを表す Direct3DTexture8 オブジェクト。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DERR_NOTAVAILABLE
D3DERR_OUTOFVIDEOMEMORY
D3DXERR_INVALIDDATA
E_OUTOFMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

PALETTEENTRY の詳細については、Microsoft Platform Software Development Kit (SDK) を参照すること。Microsoft DirectX® 8.0 の時点で、PALETTEENTRY 構造体の peFlags メンバは、Platform SDK に説明されているようには機能しない。peFlags メンバは現在、8 ビットのパレット化されたフォーマット用のアルファ チャネルである。

このメソッドは、アプリケーション定義のリソース (未加工データ) である、RT_RCDATA として格納されたイメージ ファイルをロードするために使用するように設計されている。それ以外の目的に使用すると、このメソッドは失敗する。


D3DX8.CreateTextureFromResource

リソースからテクスチャを作成する。

object.CreateTextureFromResource( _
    Device As Direct3DDevice8, _
    hModule As Long, _
    SrcResource As String) As Direct3DTexture8

指定項目

object
D3DX8 オブジェクトを表すオブジェクト式。
Device
テクスチャに関連付けられているデバイスを表す Direct3DDevice8 オブジェクト。
hModule
リソースを特定しているモジュールへのハンドル。または、リソース情報が現在のプロセスで特定される場合は App.hInstance。
SrcResource
テクスチャの作成に使用するリソースを指定する文字列。

戻り値

作成されたテクスチャ オブジェクトを表す Direct3DTexture8 オブジェクト。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DERR_NOTAVAILABLE
D3DERR_OUTOFVIDEOMEMORY
D3DXERR_INVALIDDATA
E_OUTOFMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

この関数を使用して作成したリソースは、CONST_D3DPOOL 列挙型の D3DPOOL_MANAGED メンバで示されるメモリ クラスに配置される。

参照

D3DX8.CreateTextureFromResourceEx


D3DX8.CreateTextureFromResourceEx

リソースからテクスチャを作成する。これは、D3DX8.CreateTextureFromResource よりも高度なメソッドである。

object.CreateTextureFromResourceEx( _
    Device As Direct3DDevice8, _
    hSrcModule As Long, _
    SrcResource As String, _
    Width As Long, _
    Height As Long, _
    MipLevels As Long, _
    Usage As Long, _
    PixelFormat As CONST_D3DFORMAT, _
    Pool As CONST_D3DPOOL, _
    Filter As Long, _
    MipFilter As Long, _
    ColorKey As Long, _
    SrcInfo As Any, _
    Palette As Any) As Direct3DTexture8

指定項目

object
D3DX8 オブジェクトを表すオブジェクト式。
Device
テクスチャに関連付けられているデバイスを表す Direct3DDevice8 オブジェクト。
hSrcModule
リソースを特定しているモジュールへのハンドル。または、リソース情報が現在のプロセスで特定される場合は App.hInstance。
SrcResource
テクスチャの作成に使用するリソースを指定する文字列。
Width
幅 (ピクセル単位)。この値が 0 または D3DX_DEFAULT の場合、サイズはファイルから取得される。
Height
高さ (ピクセル単位)。この値が 0 または D3DX_DEFAULT の場合、サイズはファイルから取得される。
MipLevels
要求されたミップ レベルの数。この値が 0 または D3DX_DEFAULT の場合は、完全なミップマップ チェーンが作成される。
Usage
0 または CONST_D3DUSAGEFLAGS 列挙の D3DUSAGE_RENDERTARGET メンバ。D3DUSAGE_RENDERTARGET を指定すると、そのサーフェスはレンダリング ターゲットとして使用されることを示す。リソースは、SetRenderTarget メソッドの NewRenderTarget パラメータに渡すことができる。D3DUSAGE_RENDERTARGET を指定する場合、アプリケーションは Direct3D8.CheckDeviceFormat を呼び出して、デバイスがこれらの処理をサポートしていることを確認する必要がある。
PixelFormat
テクスチャに対して要求されたピクセル フォーマットを記述する CONST_D3DFORMAT 列挙のメンバ。返されるテクスチャのフォーマットは PixelFormat で指定されたフォーマットと異なる場合がある。アプリケーションは、返されたテクスチャのフォーマットを確認する必要がある。PixelFormat が D3DFMT_UNKNOWN の場合、フォーマットはファイルから取得される。
Pool
テクスチャの配置先となるメモリ クラスを記述する、CONST_D3DPOOL 列挙のメンバ。
Filter
イメージをフィルタリングする方法を制御する、CONST_D3DXENUM 列挙で定義される 1 つ以上のフィルタ フラグの組み合わせ。このパラメータに D3DX_DEFAULT を指定することは、D3DX_FILTER_DITHER OR D3DX_FILTER_TRIANGLE を指定することと等しい。
MipFilter
イメージをフィルタリングする方法を制御する、CONST_D3DXENUM 列挙で定義される 1 つ以上のミップ フィルタ フラグの組み合わせ。このパラメータに D3DX_DEFAULT を指定することは、D3DX_FILTER_BOX を指定することと等しい。
ColorKey
透明となる値。カラーキーを無効にする場合は 0 を指定する。ソース イメージのフォーマットとは関係なく、これは常に 32 ビットの ARGB カラーである。アルファが有意であり、通常はカラーキーを不透明にする場合は FF を指定する。したがって、不透明な黒の場合、値は &HFF000000 となる。
SrcInfo
ソース イメージ ファイル内のデータの記述を格納する D3DXIMAGE_INFO 構造体、または ByVal 0。
Palette
格納する 256 PALETTEENTRY 型の配列の最初の要素、または ByVal 0。「注意」を参照すること。

戻り値

作成されたテクスチャ オブジェクトを表す Direct3DTexture8 オブジェクト。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DERR_NOTAVAILABLE
D3DERR_OUTOFVIDEOMEMORY
D3DXERR_INVALIDDATA
E_OUTOFMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

PALETTEENTRY の詳細については、Microsoft Platform Software Development Kit (SDK) を参照すること。Microsoft DirectX® 8.0 の時点で、PALETTEENTRY 構造体の peFlags メンバは、Platform SDK に説明されているようには機能しない。peFlags メンバは現在、8 ビットのパレット化されたフォーマット用のアルファ チャネルである。

参照

D3DX8.CreateTextureFromResource


D3DX8.CreateTorus

トーラスのメッシュを作成する。

object.CreateTorus( _
    D3DDevice As Direct3DDevice8, _
    InnerRadius As Single, _
    OuterRadius As Single, _
    Sides As Long, _
    Rings As Long, _
    RetAdjacency As D3DXBuffer) As D3DXMesh

指定項目

object
D3DX8 オブジェクトを表すオブジェクト式。
D3DDevice
テクスチャに関連付けられているデバイスを表す Direct3DDevice8 オブジェクト。
InnerRadius
トーラスの内部の半径。値は 0 以上である必要がある。
OuterRadius
トーラスの外部の半径。値は 0 以上である必要がある。
Sides
横断面の辺の数。値は 3 以上である必要がある。
Rings
トーラスを構成する環の数。値は 3 以上である必要がある。
RetAdjacency
D3DXBuffer オブジェクト。メソッドが返ると、このパラメータには、メッシュに含まれる各面の 3 つの隣接面を指定する、1 面あたりの 3 つの Long 値の配列が入力される。

戻り値

作成されたトーラスを表す D3DXMesh オブジェクト。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DXERR_INVALIDDATA
E_OUTOFMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

CreateTorus メソッドは、中心が (0, 0, 0) で軸が z 軸方向のドーナツ型の図形 (トーラス) を作成する。このトーラスの内部の半径は横断面の半径 (小さい方の半径)、外部の半径は中央の穴の半径である。

このメソッドは、後でアプリケーションにより描画したり、操作するときに使用できるメッシュを返す。


D3DX8.CreateVolumeTexture

必要に応じて呼び出しパラメータを調整し、空のボリューム テクスチャを作成する。

object.CreateVolumeTexture( _
    Device As Direct3DDevice8, _
    Width As Long, _
    Height As Long, _
    Depth As Long, _
    MipLevels As Long, _
    Usage As Long, _
    PixelFormat As CONST_D3DFORMAT, _
    Pool As CONST_D3DPOOL) As Direct3DVolume8

指定項目

object
D3DX8 オブジェクトを表すオブジェクト式。
Device
ボリュームに関連付けられるデバイスを表す、Direct3DDevice8 オブジェクト。
Width
幅 (ピクセル単位)。この値は 0 以外である必要がある。
Height
高さ (ピクセル単位)。この値は 0 以外である必要がある。
Depth
深度 (ピクセル単位)。この値は 0 以外である必要がある。
MipLevels
要求されたミップ レベルの数。この値が 0 または D3DX_DEFAULT の場合は、完全なミップマップ チェーンが作成される。
Usage
現時点では未使用なので 0 を設定しておく。
PixelFormat
ボリューム テクスチャに対して要求されたピクセル フォーマットを記述する CONST_D3DFORMAT 列挙のメンバ。返されるボリューム テクスチャのフォーマットは Format で指定されたフォーマットと異なる場合がある。アプリケーションは、返されたボリューム テクスチャのフォーマットを確認する必要がある。
Pool
ボリューム テクスチャの配置先となるメモリ クラスを記述する、CONST_D3DPOOL 列挙のメンバ。

戻り値

作成されたボリューム テクスチャ オブジェクトを表す、Direct3DVolume8 オブジェクト。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DERR_NOTAVAILABLE
D3DERR_OUTOFVIDEOMEMORY
E_OUTOFMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

D3DX8.CreateVolumeTexture は、内部で D3DX8.CheckVolumeTextureRequirements を使用して呼び出しパラメータを調整する。したがって、Direct3Ddevice8.CreateVolumeTexture の呼び出しが失敗する場合でも、D3DX8.CreateVolumeTexture の呼び出しは成功することが多い。


D3DX8.DeclaratorFromFVF

柔軟な頂点フォーマット (FVF) コードから宣言子を返す。

object.DeclaratorFromFVF( _
    FVF As Long, _
    Declarator As D3DXDECLARATOR)

指定項目

object
D3DX8 オブジェクトを表すオブジェクト式。
FVF
宣言子を生成する元となる FVF を記述する、柔軟な頂点フォーマット フラグの組み合わせ。
Declarator
返される宣言子を記述する、D3DXDECLARATOR 型。

エラー コード

失敗した場合はエラーが発生し、Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

参照

D3DX8.FVFFromDeclarator


D3DX8.DrawText

Microsoft® Direct3D® デバイス上に、整形したテキストを描画する。

object.DrawText( _
    D3dFont As D3DXFont, _
    Color As Long, _
    TextString As String, _
    RECT As RECT, _
    Format As Long)

指定項目

object
D3DX8 オブジェクトを表すオブジェクト式。
D3dFont
使用するフォントを指定する D3DXFont オブジェクト。
Color
テキストのカラーを指定する Long 値。
TextString
描画する文字列。
RECT
RECT 型。整形するテキストが格納される論理座標の四角形を格納する。
Format
テキストの整形方法を指定する、CONST_DTFLAGS 列挙からの値の組み合わせ。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DERR_NOTAVAILABLE
D3DERR_OUTOFVIDEOMEMORY
E_OUTOFMEMORY

エラー トラッピングの詳細については、Microsoft Visual Basic® の「エラー処理」を参照すること。

参照

CONST_DTFLAGS 、 D3DXFont.DrawTextW


D3DX8.FilterCubeTexture

キューブ テクスチャをフィルタリングする。

object.FilterCubeTexture( _
    CubeTexture As Direct3DCubeTexture8, _
    Palette As Any, _
    SrcLevel As Long, _
    MipFilter As Long)

指定項目

object
D3DX8 オブジェクトを表すオブジェクト式。
CubeTexture
フィルタリングするキューブ テクスチャを表す、Direct3DCubeTexture8 オブジェクト。
Palette
格納する 256 PALETTEENTRY 型の配列の最初の要素、または ByVal 0。パレットが指定されていない場合は、デフォルトの Microsoft® Direct3D® パレット (全部不透明な白のパレット) が提供される。「注意」を参照すること。
SrcLevel
下のレベルを生成するためにイメージを使用するレベル。このパラメータに D3DX_DEFAULT を指定することは、0 を指定することと等しい。
MipFilter
ミップマップをフィルタリングする方法を制御する、CONST_D3DXENUM 列挙で定義される 1 つ以上のフィルタ フラグの組み合わせ。このパラメータに D3DX_DEFAULT を指定することは、D3DX_FILTER_BOX を指定することと等しい。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DXERR_INVALIDDATA

エラー トラッピングの詳細については、Microsoft Visual Basic® の「エラー処理」を参照すること。

注意

PALETTEENTRY の詳細については、Microsoft Platform Software Development Kit (SDK) を参照すること。Microsoft DirectX® 8.0 の時点で、PALETTEENTRY 構造体の peFlags メンバは、Platform SDK に説明されているようには機能しない。peFlags メンバは現在、8 ビットのパレット化されたフォーマット用のアルファ チャネルである。

キューブ テクスチャの各面について、各レベルで再帰的にボックスフィルタを適用して次のレベルを生成する。


D3DX8.FilterTexture

テクスチャのミップマップ レベルをフィルタリングする。

object.FilterTexture( _
    Texture As Direct3DTexturep8, _
    Palette As Any, _
    SrcLevel As Long, _
    MipFilter As Long)

指定項目

object
D3DX8 オブジェクトを表すオブジェクト式。
Texture
フィルタリングするテクスチャを表す、Direct3DTexture8 オブジェクト。
Palette
格納する 256 PALETTEENTRY 型の配列の最初の要素、または非パレット形式の場合は ByVal 0。パレットが指定されていない場合は、デフォルトの Microsoft® Direct3D® パレット (全部不透明な白のパレット) が提供される。「注意」を参照すること。
SrcLevel
下のレベルを生成するためにイメージを使用するレベル。このパラメータに D3DX_DEFAULT を指定することは、0 を指定することと等しい。
MipFilter
ミップマップをフィルタリングする方法を制御する、CONST_D3DXENUM 列挙で定義される 1 つ以上のフィルタ フラグの組み合わせ。このパラメータに D3DX_DEFAULT を指定することは、D3DX_FILTER_BOX を指定することと等しい。

エラー コード

失敗した場合はエラーが発生し、Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

PALETTEENTRY の詳細については、Microsoft Platform Software Development Kit (SDK) を参照すること。Microsoft DirectX® 8.0 の時点で、PALETTEENTRY 構造体の peFlags メンバは、Platform SDK に説明されているようには機能しない。peFlags メンバは現在、8 ビットのパレット化されたフォーマット用のアルファ チャネルである。

各テクスチャ レベルで再帰的にボックスフィルタを適用して次のテクスチャ レベルを生成する。


D3DX8.FilterVolumeTexture

ボリューム テクスチャのミップマップ レベルをフィルタリングする。

object.FilterVolumeTexture( _
    VolumeTexture As Direct3DVolume8, _
    Palette As Any, _
    SrcLevel As Long, _
    MipFilter As Long)

指定項目

object
D3DX8 オブジェクトを表すオブジェクト式。
VolumeTexture
フィルタリングするボリュームを表す、Direct3DVolume8 オブジェクト。
Palette
格納する 256 PALETTEENTRY 型の配列の最初の要素、または非パレット形式の場合は ByVal 0。パレットが指定されていない場合は、デフォルトの Microsoft® Direct3D® パレット (全部不透明な白のパレット) が提供される。「注意」を参照すること。
SrcLevel
下のレベルを生成するためにイメージを使用するレベル。このパラメータに D3DX_DEFAULT を指定することは、0 を指定することと等しい。
MipFilter
ミップマップをフィルタリングする方法を制御する、CONST_D3DXENUM 列挙で定義される 1 つ以上のフィルタ フラグの組み合わせ。このパラメータに D3DX_DEFAULT を指定することは、D3DX_FILTER_BOX を指定することと等しい。

エラー コード

失敗した場合はエラーが発生し、Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Microsoft Visual Basic® の「エラー処理」を参照すること。

注意

PALETTEENTRY の詳細については、Microsoft Platform Software Development Kit (SDK) を参照すること。Microsoft DirectX 8.0 の時点で、PALETTEENTRY 構造体の peFlags メンバは、Platform SDK に説明されているようには機能しない。peFlags メンバは現在、8 ビットのパレット化されたフォーマット用のアルファ チャネルである。

各テクスチャ レベルで再帰的にボックスフィルタを適用して次のテクスチャ レベルを生成する。


D3DX8.FVFFromDeclarator

宣言子から柔軟な頂点フォーマット (FVF) コードを返す。

object.FVFFromDeclarator( _
    Declarator As D3DXDECLARATOR) As Long

指定項目

object
D3DX8 オブジェクトを表すオブジェクト式。
Declarator
FVF コードの生成元となる宣言子を記述する、D3DXDECLARATOR 型。

戻り値

Long 値。宣言子から返される頂点フォーマットを記述する、柔軟な頂点フォーマット フラグの組み合わせを表す。

エラー コード

失敗した場合はエラーが発生し、Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注 FVF を直接マップしない宣言子の場合、この関数は失敗する。

参照

D3DX8.DeclaratorFromFVF


D3DX8.GeneratePMesh

プログレッシブ メッシュを生成する。

object.GeneratePMesh( _
    Mesh As D3DXMesh, _
    Adjacency As Any, _
    VertexAttributeWeights As Any, _
    VertexWeights As Any, _
    MinValue As Long, _
    Options As Long) As D3DXPMesh

指定項目

object
D3DX8 オブジェクトを表すオブジェクト式。
Mesh
ソース メッシュを表す D3DXMesh オブジェクト。
Adjacency
作成されたプログレッシブ メッシュに含まれる各面の 3 つの隣接面を指定する、1 面あたりの 3 つの Long 値の配列の最初の要素。
VertexAttributeWeights
各頂点の成分に対する加重を格納する D3DXATTRIBUTEWEIGHTS 型。このパラメータを ByVal 0 に設定すると、デフォルトの型が使用される。「注意」を参照すること。
VertexWeights
頂点加重の配列の最初の要素。このパラメータを ByVal 0 に設定すると、すべての頂点加重は 1.0 に設定される。頂点加重が大きいほど、単純化されにくいことに注意する。
MinValue
Options パラメータに設定されているフラグに応じた頂点または面の数。これによって、ソース メッシュが単純化される。
Options
メッシュに対して単純化オプションを指定する。CONST_D3DXMESHSIMP 列挙で定義される次のフラグのいずれかを設定できる。

戻り値

作成されるプログレッシブ メッシュを表す、D3DXPMesh オブジェクト。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DXERR_CANNOTATTRSORT
E_OUTOFMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

このメソッドは、LOD (Level of Detail) を現在の値から MinValue まで調節可能な場合にメッシュを生成する。

単純化プロセスによってメッシュを MinValue まで減らすことができない場合でも呼び出しは継続される。これは、MinValue が絶対的な最小値ではなく、希望の最小値であるからである。

VertexAttributeWeights を ByVal 0 に設定した場合、値はデフォルトの D3DXATTRIBUTEWEIGHTS 型に従って割り当てられる。

Dim AttribruteWeights As D3DXATTRIBUTEWEIGHTS
With _
.position = 1
.Boundary = 1
.Normal = 1
.diffuse = 0
.specular = 0
.Tex(7) = 0
End With

大部分のアプリケーションでは、このデフォルトの型を使用する。デフォルトではジオメトリと法線の調整のみが考慮される。その他のメンバ フィールドを修正する必要があるのは、特別な場合のみである。

次のサンプル コードは、D3DXBuffer オブジェクトを使用して隣接性情報を渡す方法を示している。

Dim Mesh As D3DXMesh
Dim D3DXbAdjacency As D3DXBuffer
Dim VAttWeights As Any
Dim VWeights As Any
Dim MinV As Long
Dim Opts As Long

' このコードでは、すべての引数が
' 正しく初期化されていると仮定している。
Call D3DX8.GeneratePMesh(Mesh, ByVal D3DXbAdjacency.GetBufferPointer, VAttWeights, Vweights, MinV, Opts )


D3DX8.GetErrorString

エラー コードに対応するエラー文字列を返す。

object.GetErrorString( _
    ErrorCode As Long) As String

指定項目

object
D3DX8 オブジェクトを表すオブジェクト式。
ErrorCode
解読するエラー コード。

戻り値

返されたエラー文字列。

エラー コード

失敗した場合はエラーが発生し、Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Microsoft Visual Basic® の「エラー処理」を参照すること。

注意

この関数は、すべての Microsoft® Direct3D® エラー コードを解析する。


D3DX8.GetFVFVertexSize

柔軟な頂点フォーマット用に頂点のサイズを返す。

object.GetFVFVertexSize( _
    FVF As Long) As Long

指定項目

object
D3DX8 オブジェクトを表すオブジェクト式。
FVF
照会対象の柔軟な頂点フォーマット。柔軟な頂点フォーマット フラグの組み合わせ。

戻り値

柔軟な頂点フォーマットの頂点のサイズ (バイト単位)。

エラー コード

失敗した場合はエラーが発生し、Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。


D3DX8.Intersect

レイがメッシュに当たるかどうかを判定する。

object.Intersect( _
    MeshIn As D3DXMesh, _
    RayPos As D3DVECTOR, _
    RayDir As D3DVECTOR, _
    retHit As Long, _
    retFaceIndex As Long, _
    retU As Single, _
    retV As Single, _
    retDist As Single)

指定項目

object
D3DX8 オブジェクトを表すオブジェクト式。
MeshIn
テストするメッシュを表す、D3DXMesh オブジェクト。
RayPos
レイの始点座標を指定する D3DVECTOR 型。
RayDir
レイの方向を指定する D3DVECTOR 型。
retHit
レイがメッシュの三角形の面に当たる場合、この値は TRUE に設定される。それ以外の場合、この値は FALSE に設定される。
retFaceIndex
retHit が TRUE の場合、レイの始点に最も近い面のインデックス値。
retU
重心ヒット座標。
retV
重心ヒット座標。
retDist
レイの始点から交点までの距離。

エラー コード

失敗した場合はエラーが発生し、Err.Number に E_OUTOFMEMORY が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。


D3DX8.LoadPMeshFromFile

ファイルからプログレッシブ メッシュをロードする。

object.LoadPMeshFromFile( _
    Filename As String, _
    D3DDevice As Direct3DDevice8, _
    RetMaterials As D3DXBuffer, _
    RetNumMaterials As Long) As D3DXPMesh

指定項目

object
D3DX8 オブジェクトを表すオブジェクト式。
Filename
プログレッシブ メッシュのロード元となるファイルの名前を指定する文字列。
D3DDevice
プログレッシブ メッシュに関連付けられるデバイス オブジェクトである、Direct3DDevice8 オブジェクト。
RetMaterials
D3DXBuffer オブジェクト。メソッドが返ると、このパラメータには、DirectX ファイルに保存された情報を格納する D3DXMATERIAL 型の配列が入力される。
RetNumMaterials
メソッドが返ったときに RetMaterials 配列に含まれる D3DXMATERIAL 型の数。

戻り値

ロードされたプログレッシブ メッシュを表す D3DXPMesh オブジェクト。

エラー コード

失敗した場合はエラーが発生し、Err.Number に D3DXERR_INVALIDMESH が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

参照

D3DX8.SavePMeshToFile


D3DX8.LoadSkinMeshFromXof

Microsoft® DirectX® (.x) ファイル データ オブジェクトからメッシュをロードする。

object.LoadSkinMeshFromXof( _
    OfObjMesh As Unknown, _
    Options As Long, _
    D3DDevice As Direct3DDevice8, _
    RetAdjacency As D3DXBuffer, _
    RetMaterials As D3DXBuffer, _
    RetMatout As Long, _
    RetBoneNames As D3DXBuffer, _
    RetBoneTransforms As D3DXBuffer) As D3DXSkinMesh

指定項目

object
D3DX8 オブジェクトを表すオブジェクト式。
OfObjMesh
ロードする DirectX ファイル データ オブジェクトを表す、DirectXFileData オブジェクト。
Options
メッシュの作成オプションを指定する、CONST_D3DXMESH 列挙で定義される 1 つ以上のフラグの組み合わせ。
D3DDevice
メッシュに関連付けられるデバイス オブジェクトである、Direct3DDevice8 オブジェクト。
RetAdjacency
D3DXBuffer オブジェクト。メソッドが返ると、このパラメータには、メッシュに含まれる各面の 3 つの隣接面を指定する、1 面あたりの 3 つの Long 値の配列が入力される。
RetMaterials
D3DXBuffer オブジェクト。メソッドが返ると、このパラメータには、DirectX ファイルに保存された情報を格納する D3DXMATERIAL 型の配列が入力される。
RetMatout
メソッドが返ったときに RetMaterials 配列に含まれる D3DXMATERIAL 型の数。
RetBoneNames
ボーンの名前を格納する D3DXBuffer オブジェクト。
RetBoneTransforms
ボーン トランスフォームを格納する D3DXBuffer オブジェクト。

戻り値

ロードされたメッシュを表す D3DXSkinMesh オブジェクト。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DXERR_INVALIDDATA
E_OUTOFMEMORY

エラー トラッピングの詳細については、Microsoft Visual Basic® の「エラー処理」を参照すること。


D3DX8.LoadMeshFromX

Microsoft® DirectX® (.x) ファイルからメッシュをロードする。

object.LoadMeshFromX( _
    FileName As String, _
    Options As Long, _
    Device As Direct3DDevice8, _
    RetAdjacency As D3DXBuffer, _
    RetMaterials As D3DXBuffer, _
    RetMaterialCount As Long) As D3DXMesh

指定項目

object
D3DX8 オブジェクトを表すオブジェクト式。
FileName
ロードする DirectX ファイルの名前を指定する String。
Options
メッシュの作成オプションを指定する、CONST_D3DXMESH 列挙で定義される 1 つ以上のフラグの組み合わせ。
Device
メッシュに関連付けられるデバイスである、Direct3DDevice8 オブジェクト。
RetAdjacency
D3DXBuffer オブジェクト。メソッドが返ると、このパラメータには、メッシュに含まれる各面の 3 つの隣接面を指定する、1 面あたりの 3 つの Long 値の配列が入力される。
RetMaterials
D3DXBuffer オブジェクト。メソッドが返ると、このパラメータには、DirectX ファイルに保存された情報を格納する D3DXMATERIAL 型の配列が入力される。
RetMaterialCount
メソッドが返ったときに RetMaterials 配列に含まれる D3DXMATERIAL 型の数。

戻り値

ロードされたメッシュを表す D3DXMesh オブジェクト。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
E_OUTOFMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

次のコードは、LoadMeshFromX の呼び出し方である。

Dim g_device As Direct3DDevice8

Dim g_d3dx As D3DX8
Set g_d3dx = New D3DX8

Dim mesh As D3DXMesh
Dim matBuf As D3DXBuffer

' 次のコードでは、FileName、g_device、matBuf、および matCount が有効な値に設定されていると仮定している。
Set mesh = g_d3dx.LoadMeshFromX(FileName, D3DXMESH_MANAGED, g_device, Nothing, matBuf, matCount)

LoadMeshFromX が戻る場合、matBuf および matCount は有効な値に設定される。

注 ファイル内のすべてのメッシュが 1 つの出力メッシュにまとめられる。ファイルにフレーム階層が格納されている場合、すべてのトランスフォームがメッシュに適用される。

参照

D3DX8.BufferGetMaterial、D3DX8.BufferGetTextureName


D3DX8.LoadMeshFromXof

Microsoft® DirectX® (.x) ファイル データ オブジェクトからメッシュをロードする。

object.LoadMeshFromXof( _
    ofObjMesh As Unknown, _
    Options As Long, _
    Device As Direct3DDevice8, _
    RetBufAdjacency As D3DXBuffer, _
    RetMaterials As D3DXBuffer, _
    RetMaterialCount As Long) As D3DXMesh

指定項目

object
D3DX8 オブジェクトを表すオブジェクト式。
ofObjMesh
ロードする DirectX ファイル データ オブジェクトを表す、DirectXFileData オブジェクト。
Options
メッシュの作成オプションを指定する、CONST_D3DXMESH 列挙で定義される 1 つ以上のフラグの組み合わせ。
Device
メッシュに関連付けられるデバイス オブジェクトである、Direct3DDevice8 オブジェクト。
RetBufAdjacency
D3DXBuffer オブジェクト。メソッドが返ると、このパラメータには、メッシュに含まれる各面の 3 つの隣接面を指定する、1 面あたりの 3 つの Long 値の配列が入力される。
RetMaterials
D3DXBuffer オブジェクト。メソッドが返ると、このパラメータには、DirectX ファイルに保存された情報を格納する D3DXMATERIAL 型の配列が入力される。
RetMaterialCount
メソッドが返ったときに RetMaterials 配列に含まれる D3DXMATERIAL 型の数。

戻り値

ロードされたメッシュを表す D3DXMesh オブジェクト。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DXERR_INVALIDDATA
E_OUTOFMEMORY

エラー トラッピングの詳細については、Microsoft Visual Basic® の「エラー処理」を参照すること。

参照

DirectXFileData


D3DX8.LoadSurfaceFromFile

ファイルからサーフェスをロードする。

object.LoadSurfaceFromFile( _
    DestSurface As Direct3DSurface8, _
    DestPalette As Any, _
    DestRect As Any, _
    SrcFile As String, _
    SrcRect As Any, _
    Filter As Long, _
    ColorKey As Long, _
    SrcInfo)

指定項目

object
D3DX8 オブジェクトを表すオブジェクト式。
DestSurface
Direct3DSurface8 オブジェクト。転送先のサーフェスを指定する。このサーフェスがイメージを受け取る。
DestPalette
転送先のパレットを表す 256 PALETTEENTRY 型の配列の最初の要素、または ByVal 0。「注意」を参照すること。
DestRect
RECT 型。転送先矩形を指定する。このパラメータに ByVal 0 を設定して、サーフェス全体を指定する。
SrcFile
ソース イメージのファイル名を指定する String。
SrcRect
RECT 型。転送元矩形を指定する。このパラメータに ByVal 0 を設定して、イメージ全体を指定する。
Filter
イメージをフィルタリングする方法を制御する、CONST_D3DXENUM 列挙で定義される 1 つ以上のフィルタ フラグの組み合わせ。このパラメータに D3DX_DEFAULT を指定することは、D3DX_FILTER_DITHER OR D3DX_FILTER_TRIANGLE を指定することと等しい。
ColorKey
透明となる値。カラーキーを無効にする場合は 0 を指定する。ソース イメージのフォーマットとは関係なく、これは常に 32 ビットの ARGB カラーである。アルファが有意であり、通常はカラーキーを不透明にする場合は FF を指定する。したがって、不透明な黒の場合、値は &HFF000000 となる。
SrcInfo
ソース イメージ ファイル内のデータの記述を格納する D3DXIMAGE_INFO 構造体、または ByVal 0。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DXERR_INVALIDDATA

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

PALETTEENTRY の詳細については、Microsoft Platform Software Development Kit (SDK) を参照すること。Microsoft DirectX® 8.0 の時点で、PALETTEENTRY 構造体の peFlags メンバは、Platform SDK に説明されているようには機能しない。peFlags メンバは現在、8 ビットのパレット化されたフォーマット用のアルファ チャネルである。

非レベルゼロへの書き込みはアップデートすべきダーティーな矩形とはならない。D3DX8.LoadSurfaceFromFileA が呼び出され、サーフェスが既にダーティーではなかった (これは通常の使用シナリオにはない) なら、アプリケーションは明示的にそのサーフェスに Direct3DTexture8.AddDirtyRect を呼び出す必要がある。


D3DX8.LoadSurfaceFromFileInMemory

メモリ内にあるファイルからサーフェスをロードする。

object.LoadSurfaceFromFileInMemory( _
    DestSurface As Direct3DSurface8, _
    DestPalette As Any, _
    DestRect As Any, _
    SrcData As Any, _
    LengthInBytes As Long, _
    SrcRect As Any, _
    Filter As Long, _
    ColorKey As Long, _
    SrcInfo As Any)

指定項目

object
D3DX8 オブジェクトを表すオブジェクト式。
DestSurface
Direct3DSurface8 オブジェクト。転送先のサーフェスを指定する。このサーフェスがイメージを受け取る。
DestPalette
転送先のパレットを表す 256 PALETTEENTRY 型の配列の最初の要素、または ByVal 0。「注意」を参照すること。
DestRect
RECT 型。転送先矩形を指定する。このパラメータに ByVal 0 を設定して、サーフェス全体を指定する。
SrcData
ロードするサーフェスが存在するメモリ内のファイル。
LengthInBytes
メモリ内のファイルのサイズ (バイト単位)。
SrcRect
RECT 型。転送元矩形を指定する。このパラメータに ByVal 0 を設定して、イメージ全体を指定する。
Filter
イメージをフィルタリングする方法を制御する、CONST_D3DXENUM 列挙で定義される 1 つ以上のフィルタ フラグの組み合わせ。このパラメータに D3DX_DEFAULT を指定することは、D3DX_FILTER_DITHER OR D3DX_FILTER_TRIANGLE を指定することと等しい。
ColorKey
透明となる値。カラーキーを無効にする場合は 0 を指定する。ソース イメージのフォーマットとは関係なく、これは常に 32 ビットの ARGB カラーである。アルファが有意であり、通常はカラーキーを不透明にする場合は FF を指定する。したがって、不透明な黒の場合、値は &HFF000000 となる。
SrcInfo
ソース イメージ ファイル内のデータの記述を格納する D3DXIMAGE_INFO 構造体、または ByVal 0。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DXERR_INVALIDDATA

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

PALETTEENTRY の詳細については、Microsoft Platform Software Development Kit (SDK) を参照すること。Microsoft DirectX® 8.0 の時点で、PALETTEENTRY 構造体の peFlags メンバは、Platform SDK に説明されているようには機能しない。peFlags メンバは現在、8 ビットのパレット化されたフォーマット用のアルファ チャネルである。

非レベルゼロへの書き込みはアップデートすべきダーティーな矩形とはならない。D3DX8.LoadSurfaceFromFileInMemory が呼び出され、サーフェスが既にダーティーではなかった (これは通常の使用シナリオにはない) なら、アプリケーションは明示的にそのサーフェスに Direct3DTexture8.AddDirtyRect を呼び出す必要がある。


D3DX8.LoadSurfaceFromMemory

メモリからサーフェスをロードする。

object.LoadSurfaceFromMemory( _
    DestSurface As Direct3DSurface8, _
    DestPalette As Any, _
    DestRect As Any, _
    SrcData As Any, _
    SrcFormat As CONST_D3DFORMAT, _
    SrcPitch As Long, _
    SrcPalette As Any, _
    SrcRect As Any, _
    Filter As Long, _
    ColorKey As Long)

指定項目

object
D3DX8 オブジェクトを表すオブジェクト式。
DestSurface
Direct3DSurface8 オブジェクト。転送先のサーフェスを指定する。このサーフェスがイメージを受け取る。
DestPalette
転送先のパレットを表す 256 PALETTEENTRY 型の配列の最初の要素、または ByVal 0。「注意」を参照すること。
DestRect
RECT 型。転送先矩形を指定する。
SrcData
メモリ内のソース イメージの左上隅。
SrcFormat
ソース イメージのピクセル フォーマットである、CONST_D3DFORMAT 列挙のメンバ。
SrcPitch
転送元のイメージのピッチ (バイト単位)。DXT フォーマットの場合、この数値はセルで構成される 1 つの行の幅 (バイト単位) を表す。
SrcPalette
転送元のパレットを表す 256 PALETTEENTRY 型の配列の最初の要素、または ByVal 0。
SrcRect
メモリ内の転送元イメージのサイズを記述する RECT 型。
Filter
イメージをフィルタリングする方法を制御する、CONST_D3DXENUM 列挙で定義される 1 つ以上のフィルタ フラグの組み合わせ。このパラメータに D3DX_DEFAULT を指定することは、D3DX_FILTER_DITHER OR D3DX_FILTER_TRIANGLE を指定することと等しい。
ColorKey
透明となる値。カラーキーを無効にする場合は 0 を指定する。ソース イメージのフォーマットとは関係なく、これは常に 32 ビットの ARGB カラーである。アルファが有意であり、通常はカラーキーを不透明にする場合は FF を指定する。したがって、不透明な黒の場合、値は &HFF000000 となる。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DXERR_INVALIDDATA

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

PALETTEENTRY の詳細については、Microsoft Platform Software Development Kit (SDK) を参照すること。Microsoft DirectX® 8.0 の時点で、PALETTEENTRY 構造体の peFlags メンバは、Platform SDK に説明されているようには機能しない。peFlags メンバは現在、8 ビットのパレット化されたフォーマット用のアルファ チャネルである。

非レベルゼロへの書き込みはアップデートすべきダーティーな矩形とはならない。D3DX8.LoadSurfaceFromMemory が呼び出され、サーフェスが既にダーティーではなかった (これは通常の使用シナリオにはない) なら、アプリケーションは明示的にそのサーフェスに Direct3DTexture8.AddDirtyRect を呼び出す必要がある。


D3DX8.LoadSurfaceFromResource

リソースからサーフェスをロードする。

object.LoadSurfaceFromResource( _
    DestSurface As Direct3DSurface8, _
    DestPalette As Any, _
    DestRect As Any, _
    hSrcModule As Long, _
    SrcResource As String, _
    SrcRect As Any, _
    Filter As Long, _
    ColorKey As Long, _
    SrcInfo As Any)

指定項目

object
D3DX8 オブジェクトを表すオブジェクト式。
DestSurface
Direct3DSurface8 オブジェクト。転送先のサーフェスを指定する。このサーフェスがイメージを受け取る。
DestPalette
転送先のパレットを表す 256 PALETTEENTRY 型の配列の最初の要素、または ByVal 0。「注意」を参照すること。
DestRect
RECT 型。転送先矩形を指定する。このパラメータに ByVal 0 を設定して、サーフェス全体を指定する。
hSrcModule
リソースを特定しているモジュールへのハンドル。または、リソース情報が現在のプロセスで特定される場合は App.hInstance。
SrcResource
ソース イメージのファイル名を指定する文字列。
SrcRect
メモリ内の転送元イメージのサイズを記述する RECT 型。
Filter
イメージをフィルタリングする方法を制御する、CONST_D3DXENUM 列挙で定義される 1 つ以上のフィルタ フラグの組み合わせ。このパラメータに D3DX_DEFAULT を指定することは、D3DX_FILTER_DITHER OR D3DX_FILTER_TRIANGLE を指定することと等しい。
ColorKey
透明となる値。カラーキーを無効にする場合は 0 を指定する。ソース イメージのフォーマットとは関係なく、これは常に 32 ビットの ARGB カラーである。アルファが有意であり、通常はカラーキーを不透明にする場合は FF を指定する。したがって、不透明な黒の場合、値は &HFF000000 となる。
SrcInfo
ソース イメージ ファイル内のデータの記述を格納する D3DXIMAGE_INFO 構造体、または ByVal 0。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DXERR_INVALIDDATA

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

PALETTEENTRY の詳細については、Microsoft Platform Software Development Kit (SDK) を参照すること。Microsoft DirectX® 8.0 の時点で、PALETTEENTRY 構造体の peFlags メンバは、Platform SDK に説明されているようには機能しない。peFlags メンバは現在、8 ビットのパレット化されたフォーマット用のアルファ チャネルである。

非レベルゼロへの書き込みはアップデートすべきダーティーな矩形とはならない。D3DX8.LoadSurfaceFromResource が呼び出され、サーフェスが既にダーティーではなかった (これは通常の使用シナリオにはない) なら、アプリケーションは明示的にそのサーフェスに Direct3DTexture8.AddDirtyRect を呼び出す必要がある。


D3DX8.LoadSurfaceFromSurface

カラー変換を行いながら、別のサーフェスからサーフェスをロードする。

object.LoadSurfaceFromSurface( _
    DestSurface As Direct3DSurface8, _
    DestPalette As Any, _
    DestRect As Any, _
    SrcSurface As Direct3DSurface8, _
    SrcPalette As Any, _
    SrcRect As Any, _
    Filter As Long, _
    ColorKey As Long)

指定項目

object
D3DX8 オブジェクトを表すオブジェクト式。
DestSurface
Direct3DSurface8 オブジェクト。転送先のサーフェスを指定する。このサーフェスがイメージを受け取る。
DestPalette
転送先のパレットを表す 256 PALETTEENTRY 型の配列の最初の要素、または ByVal 0。「注意」を参照すること。
DestRect
RECT 型。転送先矩形を指定する。このパラメータに ByVal 0 を設定して、サーフェス全体を指定する。
SrcSurface
転送元サーフェスを表す、Direct3DSurface8 オブジェクト。
SrcPalette
転送元のパレットを表す 256 PALETTEENTRY 型の配列の最初の要素、または ByVal 0。
SrcRect
RECT 型。転送元矩形を指定する。このパラメータに ByVal 0 を設定して、サーフェス全体を指定する。
Filter
イメージをフィルタリングする方法を制御する、CONST_D3DXENUM 列挙で定義される 1 つ以上のフィルタ フラグの組み合わせ。このパラメータに D3DX_DEFAULT を指定することは、D3DX_FILTER_DITHER OR D3DX_FILTER_TRIANGLE を指定することと等しい。
ColorKey
透明となる値。カラーキーを無効にする場合は 0 を指定する。ソース イメージのフォーマットとは関係なく、これは常に 32 ビットの ARGB カラーである。アルファが有意であり、通常はカラーキーを不透明にする場合は FF を指定する。したがって、不透明な黒の場合、値は &HFF000000 となる。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DXERR_INVALIDDATA

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

PALETTEENTRY の詳細については、Microsoft Platform Software Development Kit (SDK) を参照すること。Microsoft DirectX® 8.0 の時点で、PALETTEENTRY 構造体の peFlags メンバは、Platform SDK に説明されているようには機能しない。peFlags メンバは現在、8 ビットのパレット化されたフォーマット用のアルファ チャネルである。

非レベルゼロへの書き込みはアップデートすべきダーティーな矩形とはならない。D3DX8.LoadSurfaceFromSurface が呼び出され、サーフェスが既にダーティーではなかった (これは通常の使用シナリオにはない) なら、アプリケーションは明示的にそのサーフェスに Direct3DTexture8.AddDirtyRect を呼び出す必要がある。


D3DX8.LoadVolumeFromMemory

メモリからボリュームをロードする。

object.LoadVolumeFromMemory( _
    DestVolume As Direct3DVolume8, _
    DestPalette As Any, _
    DestBox As Any, _
    SrcMemory As Any, _
    SrcFormat As Long, _
    SrcRowPitch As Long, _
    SrcSlicePitch As Long, _
    SrcPalette As Any, _
    SrcBox As D3DBOX, _
    Filter As Long, _
    ColorKey As Long)

指定項目

object
D3DX8 オブジェクトを表すオブジェクト式。
DestVolume
Direct3DVolume8 オブジェクト。イメージを受け取る転送先のボリュームを指定する。
DestPalette
転送先のパレットを表す 256 PALETTEENTRY 型の配列の最初の要素、または ByVal 0。「注意」を参照すること。
DestBox
D3DBOX 型。転送先のボックスを指定する。このパラメータを ByVal 0 に設定して、ボリューム全体を指定する。
SrcMemory
メモリ内にあるソース ボリュームの左上隅を指定する値。
SrcFormat
ソース ボリュームのピクセル フォーマットである、CONST_D3DFORMAT 列挙のメンバ。
SrcRowPitch
転送元のイメージのピッチ (バイト単位)。DXT フォーマット (圧縮されたテクスチャ フォーマット) の場合、この数値はセルで構成される 1 つの行のサイズ (バイト単位) を表す。
SrcSlicePitch
転送元のイメージのピッチ (バイト単位)。DXT フォーマット (圧縮されたテクスチャ フォーマット) の場合、この数値はセルで構成される 1 つのスライスのサイズ (バイト単位) を表す。
SrcPalette
転送元のパレットを表す 256 PALETTEENTRY 型の配列の最初の要素、または ByVal 0。
SrcBox
D3DBOX 型。転送元のボックスを指定する。ByVal 0 はこのパラメータの有効な値ではない。
Filter
イメージをフィルタリングする方法を制御する、CONST_D3DXENUM 列挙で定義される 1 つ以上のフィルタ フラグの組み合わせ。このパラメータに D3DX_DEFAULT を指定することは、D3DX_FILTER_DITHER OR D3DX_FILTER_TRIANGLE を指定することと等しい。
ColorKey
透明となる値。カラーキーを無効にする場合は 0 を指定する。ソース イメージのフォーマットとは関係なく、これは常に 32 ビットの ARGB カラーである。アルファが有意であり、通常はカラーキーを不透明にする場合は FF を指定する。したがって、不透明な黒の場合、値は &HFF000000 となる。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DXERR_INVALIDDATA

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

PALETTEENTRY の詳細については、Microsoft Platform Software Development Kit (SDK) を参照すること。Microsoft DirectX® 8.0 の時点で、PALETTEENTRY 構造体の peFlags メンバは、Platform SDK に説明されているようには機能しない。peFlags メンバは現在、8 ビットのパレット化されたフォーマット用のアルファ チャネルである。

非レベルゼロへの書き込みはアップデートすべきダーティーな矩形とはならない。D3DX8.LoadVolumeFromMemory が呼び出され、サーフェスが既にダーティーではなかった (これは通常の使用シナリオにはない) なら、アプリケーションは明示的にそのサーフェスに Direct3DTexture8.AddDirtyRect を呼び出す必要がある。


D3DX8.LoadVolumeFromVolume

別のボリュームからボリュームをロードする。

object.LoadVolumeFromVolume( _
    DestVolume As Direct3DVolume8, _
    DestPalette As Any, _
    DestBox As Any, _
    SrcVolume As Direct3DVolume8, _
    SrcPalette As Any, _
    SrcBox As Any, _
    Filter As Long, _
    ColorKey As Long)

指定項目

object
D3DX8 オブジェクトを表すオブジェクト式。
DestVolume
Direct3DVolume8 オブジェクト。イメージを受け取る転送先のボリュームを指定する。
DestPalette
転送先のパレットを表す 256 PALETTEENTRY 型の配列の最初の要素、または ByVal 0。「注意」を参照すること。
DestBox
D3DBOX 型。転送先のボックスを指定する。このパラメータを ByVal 0 に設定して、ボリューム全体を指定する。
SrcVolume
Direct3DVolume8 オブジェクト。ソース ボリュームを指定する。
SrcPalette
転送元のパレットを表す 256 PALETTEENTRY 型の配列の最初の要素、または ByVal 0。
SrcBox
D3DBOX 型。転送元のボックスを指定する。このパラメータを ByVal 0 に設定して、ボリューム全体を指定する。
Filter
イメージをフィルタリングする方法を制御する、CONST_D3DXENUM 列挙で定義される 1 つ以上のフィルタ フラグの組み合わせ。このパラメータに D3DX_DEFAULT を指定することは、D3DX_FILTER_DITHER OR D3DX_FILTER_TRIANGLE を指定することと等しい。
ColorKey
透明となる値。カラーキーを無効にする場合は 0 を指定する。ソース イメージのフォーマットとは関係なく、これは常に 32 ビットの ARGB カラーである。アルファが有意であり、通常はカラーキーを不透明にする場合は FF を指定する。したがって、不透明な黒の場合、値は &HFF000000 となる。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DXERR_INVALIDDATA

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

PALETTEENTRY の詳細については、Microsoft Platform Software Development Kit (SDK) を参照すること。Microsoft DirectX® 8.0 の時点で、PALETTEENTRY 構造体の peFlags メンバは、Platform SDK に説明されているようには機能しない。peFlags メンバは現在、8 ビットのパレット化されたフォーマット用のアルファ チャネルである。

非レベルゼロへの書き込みはアップデートすべきダーティーな矩形とはならない。D3DX8.LoadVolumeFromVolume が呼び出され、サーフェスが既にダーティーではなかった (これは通常の使用シナリオにはない) なら、アプリケーションは明示的にそのサーフェスに Direct3DTexture8.AddDirtyRect を呼び出す必要がある。


D3DX8.SaveMeshToX

メッシュを Microsoft® DirectX® (.x) ファイルに保存する。

object.SaveMeshToX( _
    FileName As String, _
    Mesh As D3DXMesh, _
    AdjacencyArray As Any, _
    MaterialArray As D3DXMATERIAL, _
    MaterialCount As Long, _
    xFormat As Long)

指定項目

object
D3DX8 オブジェクトを表すオブジェクト式。
FileName
保存されるメッシュを指定する DirectX ファイルの名前を指定する String。
Mesh
DirectX ファイルに保存するメッシュを表す、D3DXMesh オブジェクト。
AdjacencyArray
メッシュに含まれる各面の 3 つの隣接面を指定する、1 面あたりの 3 つの Long 値の配列の最初の要素。
MaterialArray
DirectX ファイルに保存されているマテリアル情報を格納する、D3DXMATERIAL 型の配列の最初の要素。
MaterialCount
MaterialArray array 内の D3DXMATERIAL 型の数。
xFormat
DirectX ファイルの保存に使用するフォーマットを指定する、CONST_DXFILEFORMATFLAGS 列挙のメンバ。

エラー コード

失敗した場合はエラーが発生し、Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

ファイル フォーマットの既定値は、DXFILEFORMAT_BINARY である。ファイル フォーマットの値は、論理和を使用して組み合わせることが可能で、圧縮済みテキスト ファイルや圧縮済みバイナリ ファイルを作成できる。ファイルがバイナリ (0) とテキスト (1) の両方で指定されている場合、テキスト ファイルで保存される。これは、0 + 1 = 1 となることからテキスト ファイル フォーマットの値と区別が付かないためである。ファイル フォーマットをテキストと圧縮の両方として指定した場合、ファイルはまずテキストとして出力されてから圧縮される。ただし、圧縮済みテキスト ファイルはバイナリ テキスト ファイルほど効率は良くない。そのため、通常はバイナリと圧縮を指定する。フォーマットを指定せずにファイルを圧縮するよう設定すると、バイナリの圧縮ファイルとなる。


D3DX8.SavePMeshToFile

プログレッシブ メッシュをファイルに保存する。

object.SavePMeshToFile( _
    Filename As String, _
    Mesh As D3DXPMesh, _
    MaterialArray As D3DXMATERIAL, _
    MaterialCount As Long)

指定項目

object
D3DX8 オブジェクトを表すオブジェクト式。
Filename
プログレッシブ メッシュを保存するファイルの名前を指定する文字列。
Mesh
ファイルに保存するプログレッシブ メッシュを表す、D3DXPMesh オブジェクト。
MaterialArray
ファイルに保存されているマテリアル情報を格納する、D3DXMATERIAL 型の配列の最初の要素。
MaterialCount
MaterialArray 内の D3DXMATERIAL 型の数。

エラー コード

失敗した場合はエラーが発生し、Err.Number に D3DXERR_INVALIDMESH が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

参照

D3DX8.LoadPMeshFromFile


D3DX8.SimplifyMesh

メッシュを単純化する。

object.SimplifyMesh( _
    Mesh As D3DXMesh, _
    Adjacency As Any, _
    VertexAttributeWeights As Any, _
    VertexWeights As Any, _
    MinValue As Long, _
    Options As Long) As D3DXMesh

指定項目

object
D3DX8 オブジェクトを表すオブジェクト式。
Mesh
ソース メッシュを表す D3DXMesh オブジェクト。
Adjacency
単純化するメッシュに含まれる各面の 3 つの隣接面を指定する、1 面あたりの 3 つの Long 値の配列の最初の要素。
VertexAttributeWeights
各頂点の成分に対する加重を格納する D3DXATTRIBUTEWEIGHTS 型。このパラメータを ByVal 0 に設定すると、デフォルトの型が使用される。「注意」を参照すること。
VertexWeights
頂点加重の配列の最初の要素。このパラメータを ByVal 0 に設定すると、すべての頂点加重は 1.0 に設定される。
MinValue
Options パラメータに設定されているフラグに応じた頂点または面の数。これによって、ソース メッシュが単純化される。
Options
メッシュに対して単純化オプションを指定する。CONST_D3DXMESHSIMP 列挙で定義されるフラグのうちの 1 つを設定できる。

戻り値

返された単純化メッシュを表す、D3DXMesh オブジェクト。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
E_OUTOFMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

このメソッドは、MinValue の頂点または面を持つメッシュを生成する。

単純化プロセスによってメッシュを MinValue まで減らすことができない場合でも呼び出しは継続される。これは、MinValue が絶対的な最小値ではなく、希望の最小値であるからである。

VertexAttributeWeights を ByVal 0 に設定した場合、値はデフォルトの D3DXATTRIBUTEWEIGHTS 型に従って割り当てられる。

Dim AttribruteWeights As D3DXATTRIBUTEWEIGHTS
With _
.position = 1
.Boundary = 1
.Normal = 1
.diffuse = 0
.specular = 0
.Tex(7) = 0
End With

大部分のアプリケーションでは、このデフォルトの型を使用する。デフォルトではジオメトリと法線の調整のみが考慮される。その他のメンバ フィールドを修正する必要があるのは、特別な場合のみである。

次のサンプル コードは、D3DXBuffer オブジェクトを使用して隣接性情報を渡す方法を示している。

Dim Mesh As D3DXMesh
Dim D3DXbAdjacency As D3DXBuffer
Dim VAttWeights As Any
Dim VWeights As Any
Dim MinV As Long
Dim Opts As Long

' このコードでは、すべての引数が
' 正しく初期化されていると仮定している。
Call D3DX8.SimplifyMesh(Mesh, ByVal D3DXbAdjacency.GetBufferPointer, VAttWeights, Vweights, MinV, Opts )


D3DX8.SphereBoundProbe

レイが境界球のボリュームに当たるかどうかを判定する。

object.SphereBoundProbe( _
    Center As D3DVECTOR, _
    Radius As Single, _
    RayPosition As D3DVECTOR, _
    Raydirection As D3DVECTOR) As Boolean

指定項目

object
D3DX8 オブジェクトを表すオブジェクト式。
Center
球の中心座標を指定する D3DVECTOR 型。
Radius
球の半径。
RayPosition
レイの始点座標を指定する D3DVECTOR 型。
Raydirection
レイの方向を指定する D3DVECTOR 型。

戻り値

レイが境界球のボリュームに当たる場合は、TRUE を返す。それ以外の場合は、FALSE を返す。

エラー コード

失敗した場合はエラーが発生し、Err.Number に D3DXERR_INVALIDMESH が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

D3DXSphereBoundProbe は、レイが球のサーフェスだけではなく、境界球のボリュームに当たるかどうかを判定する。


D3DX8.TesselateMesh

メッシュをテッセレートする。

object.TesselateMesh( _
    MeshIn As D3DXMesh, _
    AdjacencyArray As Long, _
    NumSegs As Long, _
    QuadraticInterpNormals As Boolean) As D3DXMesh

指定項目

object
D3DX8 オブジェクトを表すオブジェクト式。
MeshIn
テッセレートするメッシュを表す、D3DXMesh オブジェクト。
AdjacencyArray
ソース メッシュに含まれる各面の 3 つの隣接面を指定する、1 面あたりの 3 つの Long 値の配列の最初の要素。
NumSegs
テッセレートするエッジあたりのセグメント数。
QuadraticInterpNormals
Boolean。法線に対して二次補間を使用する場合は、TRUE に設定する。

戻り値

テッセレーションされたメッシュを表す、D3DXMesh オブジェクト。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DXERR_INVALIDDATA
E_OUTOFMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注 この関数は、n-Patch アルゴリズムを使ってテッセレートする。


D3DX8.ValidMesh

メッシュを検証する。

object.ValidMesh( _
    MeshIn As D3DXMesh, _
    Adjacency As Long) As Boolean

指定項目

object
D3DX8 オブジェクトを表すオブジェクト式。
MeshIn
テッセレートするメッシュを表す、D3DXMesh オブジェクト。
Adjacency
ソース メッシュに含まれる各面の 3 つの隣接面を指定する、1 面あたりの 3 つの Long 値の配列の最初の要素。

戻り値

MeshIn が有効な場合は TRUE を返す。それ以外の場合は FALSE を返す。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DXERR_INVALIDDATA
D3DXERR_INVALIDMESH
E_OUTOFMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

次のサンプル コードは、D3DXBuffer オブジェクトを使用して隣接性情報を渡す方法を示している。

Dim Mesh As D3DXMesh
Dim D3DXbAdjacency As D3DXBuffer

' このコードでは、すべての引数が
' 正しく初期化されていると仮定している。
Call D3DX8.GeneratePMesh(Mesh, ByVal D3DXbAdjacency.GetBufferPointer)


D3DXBaseMesh

アプリケーションは、D3DXBaseMesh クラスのメソッドを使用して、メッシュやプログレッシブ メッシュのオブジェクトの操作や照会を行う。

D3DXBaseMesh クラスのメソッドは、以下のグループにまとめることができる。

バッファ | GetIndexBuffer
 | GetVertexBuffer
 | LockIndexBuffer
 | LockVertexBuffer
 | UnlockIndexBuffer
 | UnlockVertexBuffer
コピー | CloneMesh
 | CloneMeshFVF
面 | GetNumFaces
情報 | GetDevice
 | GetOptions
レンダリング | DrawSubset
 | GetAttributeTable
頂点 | GetDeclaration
 | GetFVF
 | GetNumVertices

参照

D3DXMesh、D3DXPMesh


D3DXBaseMesh.CloneMesh

宣言子を使用して、メッシュのコピーを作成する。

object.CloneMesh( _
    Options As Long, _
    Declaration As Any, _
    Device As Direct3DDevice8) As D3DXMesh

指定項目

object
D3DXBaseMesh オブジェクトを表すオブジェクト式。
Options
メッシュの作成オプションを指定する、CONST_D3DXMESH 列挙で定義される 1 つ以上のフラグの組み合わせ。
Declaration
出力メッシュに含まれる頂点の頂点フォーマットを記述する宣言子を表す、Long 値の配列の最初の要素。
Device
メッシュに関連付けられているデバイス オブジェクトを表す Direct3DDevice8 オブジェクト。

戻り値

コピーされたメッシュを表す D3DXMesh オブジェクト。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
E_OUTOFMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

対象

このメソッドは次のクラスに適用される。これらのクラスは、D3DXBaseMesh のメソッドを実装する。

  • D3DXMesh
  • D3DXPMesh

参照

D3DX8.DeclaratorFromFVF、D3DXBaseMesh.GetDeclaration


D3DXBaseMesh.CloneMeshFVF

柔軟な頂点フォーマット (FVF) コードを使用してメッシュのコピーを作成する。

object.CloneMeshFVF( _
    Options As Long, _
    FVF As Long, _
    Device As Direct3DDevice8) As D3DXMesh

指定項目

object
D3DXBaseMesh オブジェクトを表すオブジェクト式。
Options
メッシュの作成オプションを指定する、CONST_D3DXMESH 列挙で定義される 1 つ以上のフラグの組み合わせ。
FVF
出力メッシュに含まれる頂点の頂点フォーマットを指定する柔軟な頂点フォーマット フラグの組み合わせ。
Device
メッシュに関連付けられているデバイス オブジェクトを表す Direct3DDevice8 オブジェクト。

戻り値

コピーされたメッシュを表す D3DXMesh オブジェクト。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
E_OUTOFMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

対象

このメソッドは次のクラスに適用される。これらのクラスは、D3DXBaseMesh のメソッドを実装する。

  • D3DXMesh
  • D3DXPMesh

注意

CloneMeshFVF を使用して、メッシュを 1 つの FVF から別の FVF に変換できる。

参照

D3DX8.FVFFromDeclarator、D3DXBaseMesh.GetFVF


D3DXBaseMesh.DrawSubset

メッシュのサブセットを描画する。

object.DrawSubset( _
    attribId  As Long)

指定項目

object
D3DXBaseMesh オブジェクトを表すオブジェクト式。
attribId
描画するメッシュのサブセットを指定する Long 値。この値は、メッシュ内の面を、1 つ以上の属性グループに属しているとして区別するために使用される。

エラー コード

失敗した場合はエラーが発生し、Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

対象

このメソッドは次のクラスに適用される。これらのクラスは、D3DXBaseMesh のメソッドを実装する。

  • D3DXMesh
  • D3DXPMesh

注意

属性テーブルは、異なるテクスチャ、レンダリング ステート、マテリアルなどによって描画する必要があるメッシュの領域を識別するために使用される。さらにアプリケーションは、属性テーブルを使用し、フレームの描画時に所定の属性識別子 (attribId) を描画しないことによって、メッシュの一部を隠すことができる。

参照

D3DXBaseMesh.GetAttributeTable


D3DXBaseMesh.GetAttributeTable

メッシュの属性テーブル、またはメッシュの属性テーブルに格納されているエントリの数を取得する。

object.GetAttributeTable( _
    AttribTable As Any, _
    AttribTabSize As Long)

指定項目

object
D3DXBaseMesh オブジェクトを表すオブジェクト式。
AttribTable
メッシュの属性テーブルに格納されているエントリを表す、D3DXATTRIBUTERANGE 型の配列の最初の要素。AttribTabSize の値を取得するには、ByVal 0 を指定する。
AttribTabSize
AttribTable に格納されているエントリ数、またはメッシュの属性テーブルに格納されているエントリ数で埋める値のどちらかである。

エラー コード

失敗した場合はエラーが発生し、Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

対象

このメソッドは次のクラスに適用される。これらのクラスは、D3DXBaseMesh のメソッドを実装する。

  • D3DXMesh
  • D3DXPMesh

注意

属性テーブルは、D3DXMesh.Optimize で、Flags パラメータの D3DXMESHOPT_ATTRSORT を渡すことによって作成される。

属性テーブルは、異なるテクスチャ、レンダリング ステート、マテリアルなどによって描画する必要があるメッシュの領域を識別するために使用される。さらにアプリケーションは、属性テーブルを使用し、フレームの描画時に所定の属性識別子を描画しないことによって、メッシュの一部を隠すことができる。


D3DXBaseMesh.GetDeclaration

メッシュに含まれる頂点を記述する宣言を取得する。

object.GetDeclaration( _
    Declaration As Long)

指定項目

object
D3DXBaseMesh オブジェクトを表すオブジェクト式。
Declaration
照会されたメッシュに含まれる頂点の頂点フォーマットを記述する配列の最初の要素。この宣言子の配列の上限は MAX_FVF_DECL_SIZE で、宣言子を 15 Long 値の最大数に制限する。「注意」を参照すること。

エラー コード

失敗した場合はエラーが発生し、Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

対象

このメソッドは次のクラスに適用される。これらのクラスは、D3DXBaseMesh のメソッドを実装する。

  • D3DXMesh
  • D3DXPMesh

注意

このコードは、D3DXDECLARATOR を渡してメッシュの宣言を取得する方法を示している。このコードでは、メッシュを格納している既存の D3DXMesh オブジェクト (d3dxm) があると仮定している。

Dim d3dxd As D3DXDECLARATOR

'このコードでは (d3dxm) が正しく初期化されていると仮定している。
Call d3dxd.GetDeclaration(d3dxd.Value(0))

参照

D3DXBaseMesh.GetFVF


D3DXBaseMesh.GetDevice

メッシュに関連付けられているデバイスを取得する。

object.GetDevice() As Direct3DDevice8

指定項目

object
D3DXBaseMesh オブジェクトを表すオブジェクト式。

戻り値

メッシュに関連付けられる Microsoft® Direct3D® デバイスを識別する、Direct3DDevice8 オブジェクト。

エラー コード

失敗した場合はエラーが発生し、Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

対象

このメソッドは次のクラスに適用される。これらのクラスは、D3DXBaseMesh のメソッドを実装する。

  • D3DXMesh
  • D3DXPMesh


D3DXBaseMesh.GetFVF

メッシュに含まれる頂点の柔軟な頂点フォーマットを取得する。

object.GetFVF() As Long

指定項目

object
D3DXBaseMesh オブジェクトを表すオブジェクト式。

戻り値

照会されたメッシュに含まれる頂点の柔軟な頂点フォーマットを記述する、柔軟な頂点フォーマット フラグの組み合わせを返す。

エラー コード

失敗した場合はエラーが発生し、Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

対象

このメソッドは次のクラスに適用される。これらのクラスは、D3DXBaseMesh のメソッドを実装する。

  • D3DXMesh
  • D3DXPMesh

参照

D3DXBaseMesh.GetDeclaration


D3DXBaseMesh.GetIndexBuffer

インデックス バッファ内のデータを取得する。

object.GetIndexBuffer() As Direct3DIndexBuffer8

指定項目

object
D3DXBaseMesh オブジェクトを表すオブジェクト式。

戻り値

メッシュに関連付けられているインデックス バッファ オブジェクトを表す、Direct3DIndexBuffer8 オブジェクト。

エラー コード

失敗した場合はエラーが発生し、Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

対象

このメソッドは次のクラスに適用される。これらのクラスは、D3DXBaseMesh のメソッドを実装する。

  • D3DXMesh
  • D3DXPMesh


D3DXBaseMesh.GetNumFaces

メッシュに含まれる面の数を取得する。

object.GetNumFaces() As Long

指定項目

object
D3DXBaseMesh オブジェクトを表すオブジェクト式。

戻り値

メッシュに含まれる面の数を返す。

エラー コード

失敗した場合はエラーが発生し、Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

対象

このメソッドは次のクラスに適用される。これらのクラスは、D3DXBaseMesh のメソッドを実装する。

  • D3DXMesh
  • D3DXPMesh


D3DXBaseMesh.GetNumVertices

メッシュに含まれる頂点の数を取得する。

object.GetNumVertices() As Long

指定項目

object
D3DXBaseMesh オブジェクトを表すオブジェクト式。

戻り値

メッシュに含まれる頂点の数を返す。

エラー コード

失敗した場合はエラーが発生し、Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

対象

このメソッドは次のクラスに適用される。これらのクラスは、D3DXBaseMesh のメソッドを実装する。

  • D3DXMesh
  • D3DXPMesh


D3DXBaseMesh.GetOptions

このメッシュの作成時に有効になっているメッシュ オプションを取得する。

object.GetOptions() As Long

指定項目

object
D3DXBaseMesh オブジェクトを表すオブジェクト式。

戻り値

このメッシュの作成時に有効になっているオプションを示す、CONST_D3DXMESH 列挙で定義される 1 つ以上のフラグの組み合わせを返す。

エラー コード

失敗した場合はエラーが発生し、Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

対象

このメソッドは次のクラスに適用される。これらのクラスは、D3DXBaseMesh のメソッドを実装する。

  • D3DXMesh
  • D3DXPMesh


D3DXBaseMesh.GetVertexBuffer

頂点バッファを取得する。

object.GetVertexBuffer() As Direct3DVertexBuffer8

指定項目

object
D3DXBaseMesh オブジェクトを表すオブジェクト式。

戻り値

メッシュに関連付けられている頂点バッファ オブジェクトを表す、Direct3DVertexBuffer8 オブジェクト。

エラー コード

失敗した場合はエラーが発生し、Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

対象

このメソッドは次のクラスに適用される。これらのクラスは、D3DXBaseMesh のメソッドを実装する。

  • D3DXMesh
  • D3DXPMesh


D3DXBaseMesh.LockIndexBuffer

インデックス バッファをロックし、インデックス バッファ メモリにアクセスできる状態にする。

object.LockIndexBuffer( _
    Flags As Long) As Long

指定項目

object
D3DXBaseMesh オブジェクトを表すオブジェクト式。
Flags
CONST_D3DLOCKFLAGS 列挙によって定義される、1 つ以上の有効なロッキング フラグで構成される組み合わせ。インデックス バッファ メモリをロックする方法を指定する。

戻り値

ロックされたインデックス データへのアクセスを提供する Long 値を返す。

エラー コード

失敗した場合はエラーが発生し、Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

対象

このメソッドは次のクラスに適用される。これらのクラスは、D3DXBaseMesh のメソッドを実装する。

  • D3DXMesh
  • D3DXPMesh

注意

インデックス バッファを操作するときは、複数のロック呼び出しを実行できる。ただし、ロック呼び出しの数とロック解除呼び出しの数を一致させる必要がある。現在設定されているインデックス バッファに未処理のロック カウントがある場合、DrawPrimitive 呼び出しは成功しない。

参照

D3DXBaseMesh.UnlockIndexBuffer


D3DXBaseMesh.LockVertexBuffer

頂点バッファをロックし、頂点バッファ メモリへアクセスできる状態にする。

object.LockVertexBuffer( _
    Flags As Long) As Long

指定項目

object
D3DXBaseMesh オブジェクトを表すオブジェクト式。
Flags
CONST_D3DLOCKFLAGS 列挙によって定義される、1 つ以上の有効なロッキング フラグで構成される組み合わせ。頂点バッファ メモリのロック方法を指定する。

戻り値

ロックされた頂点データへのアクセスを提供する Long 値を返す。

エラー コード

失敗した場合はエラーが発生し、Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

対象

このメソッドは次のクラスに適用される。これらのクラスは、D3DXBaseMesh のメソッドを実装する。

  • D3DXMesh
  • D3DXPMesh

注意

頂点バッファを操作するときは、複数のロック呼び出しを実行できる。ただし、ロック呼び出しの数とロック解除呼び出しの数を一致させる必要がある。現在設定されている頂点バッファに未処理のロック カウントがある場合、DrawPrimitive 呼び出しは成功しない。

参照

D3DXBaseMesh.UnlockVertexBuffer


D3DXBaseMesh.UnlockIndexBuffer

インデックス バッファのロックを解除する。

object.UnlockIndexBuffer()

指定項目

object
D3DXBaseMesh オブジェクトを表すオブジェクト式。

エラー コード

失敗した場合はエラーが発生し、Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

対象

このメソッドは次のクラスに適用される。これらのクラスは、D3DXBaseMesh のメソッドを実装する。

  • D3DXMesh
  • D3DXPMesh

参照

D3DXBaseMesh.LockIndexBuffer


D3DXBaseMesh.UnlockVertexBuffer

頂点バッファのロックを解除する。

object.UnlockVertexBuffer()

指定項目

object
D3DXBaseMesh オブジェクトを表すオブジェクト式。

エラー コード

失敗した場合はエラーが発生し、Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

対象

このメソッドは次のクラスに適用される。これらのクラスは、D3DXBaseMesh のメソッドを実装する。

  • D3DXMesh
  • D3DXPMesh

参照

D3DXBaseMesh.LockVertexBuffer


D3DXBuffer

D3DXBuffer クラスはデータ バッファとして使用され、メッシュの最適化およびロードの操作時に、頂点、隣接性、およびマテリアルに関する情報を格納する。バッファ オブジェクトは、任意の長さのデータを返すために使用される。

さらにバッファ オブジェクトは、頂点シェーダとピクセル シェーダを組み立てるメソッドに含まれるオブジェクト コードとエラー メッセージを返すために使用される。

D3DXBuffer クラスは、D3DX8.CreateBuffer メソッドを呼び出すことによって取得する。

D3DXBuffer クラスのメソッドは、以下のグループにまとめることができる。

情報 | GetBufferPointer
 | GetBufferSize


D3DXBuffer.GetBufferPointer

バッファ内のデータに対するハンドルを取得する。

object.GetBufferPointer() As Long

指定項目

object
D3DXBuffer オブジェクトを表すオブジェクト式。

戻り値

バッファ内のデータに対するハンドルを返す。

エラー コード

失敗した場合はエラーが発生し、Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

参照

D3DX8.BufferGetData、D3DX8.BufferGetMaterial、D3DX8.BufferGetTextureName、D3DX8.BufferSetData


D3DXBuffer.GetBufferSize

バッファ内のデータの合計サイズを取得する。

object.GetBufferSize() As Long

指定項目

object
D3DXBuffer オブジェクトを表すオブジェクト式。

戻り値

バッファ内のデータの合計サイズを返す (バイト単位)。

エラー コード

失敗した場合はエラーが発生し、Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。


D3DXFont

D3DXFont クラスは、特定デバイス上の特定のフォントをレンダリングするために必要なテクスチャとリソースをカプセル化するために使用する。

D3DXFont クラスは、D3DX8.CreateFont メソッドを呼び出すことによって取得する。

D3DXFont クラスのメソッドは、以下のグループにまとめることができる。

描画 | Begin
 | DrawTextW
 | End
情報 | GetDevice
 | GetLogFont


D3DXFont.Begin

テキストを描画できるようにデバイスを準備する。

object.Begin()

指定項目

object
D3DXFont オブジェクトを表すオブジェクト式。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DXERR_INVALIDDATA

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

このメソッドはオプションである。DrawTextW メソッドが Begin と D3DXFont.End の対の外側で呼び出された場合、Microsoft® Direct3D® により Begin と End が呼び出される。


D3DXFont.DrawTextW

Microsoft® Direct3D® デバイス上に、整形したテキストを描画する。

object.DrawTextW( _
    Text As String, _
    Count As Long, _
    DestRECT As RECT, _
    Format As Long, _
    Color As Long) As Long

指定項目

object
D3DXFont オブジェクトを表すオブジェクト式。
Text
描画する文字列。
Count
文字列に含まれる文字の数を指定する。Count が -1 の場合、DrawTextW は自動的に文字カウント計算する。Format に DT_MODIFYSTRING が含まれる場合、-1 は指定できない。
DestRECT
RECT 型。整形するテキストが格納される論理座標の四角形を格納する。
Format
テキストの整形方法を指定する、CONST_DTFLAGS 列挙からの値の組み合わせ。Format に DT_MODIFYSTRING が含まれる場合、この文字列には、関数によって最高 4 文字が追加されることがある。文字列を格納するバッファには、これらの追加文字を格納できる十分な大きさが必要である。
Color
テキストのカラーを指定する、D3DCOLORVALUE 型。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DERR_NOTAVAILABLE
D3DERR_OUTOFVIDEOMEMORY
E_OUTOFMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

DrawTextW メソッドは、デバイス コンテキストで選択されたフォント、テキスト カラー、バックグラウンド カラーを使用してテキストを描画する。DT_NOCLIP フォーマットが使用される場合を除き、DrawText は指定された四角形の外側にテキストがはみ出ないようテキストをクリップする。DT_SINGLELINE フォーマットが指定されている場合を除き、整形処理では複数行が対象であると見なされる。

選択したフォントが大きすぎて四角形に収まらない場合、DrawTextW メソッドは小さいフォントで置き換える処理を行わない。

DrawTextW メソッドは、escapement と orientation の両方がゼロのフォントのみサポートする。


D3DXFont.End

D3DXFont.Begin が呼び出された時点のデバイスの状態を復元する。

object.End()

指定項目

object
D3DXFont オブジェクトを表すオブジェクト式。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DXERR_INVALIDDATA

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

参照

D3DXFont.Begin


D3DXFont.GetDevice

フォント オブジェクトに関連付けられている Microsoft® Direct3D® デバイスを取得する。

object.GetDevice() As Direct3DDevice8

指定項目

object
D3DXFont オブジェクトを表すオブジェクト式。

戻り値

フォント オブジェクトに関連付けられている Direct3D デバイス オブジェクトを表す Direct3DDevice8 オブジェクト。

エラー コード

失敗した場合はエラーが発生し、Err.Number に E_OUTOFMEMORY が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。


D3DXFont.GetLogFont

フォントの属性を取得する。

object.GetLogFont(LogFont As LOGFONT)

指定項目

object
D3DXFont オブジェクトを表すオブジェクト式。
LogFont
フォントの属性を格納する LOGFONT 型。

エラー コード

失敗した場合はエラーが発生し、Err.Number に E_OUTOFMEMORY が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。


D3DXMesh

アプリケーションは、D3DXMesh クラスのメソッドを使用してメッシュ オブジェクトを操作する。

D3DXMesh クラスは、D3DX8.CreateMesh メソッド、または D3DX8.CreateMeshFVF メソッドを呼び出すことによって取得する。

D3DXMesh クラスは以下に示す D3DXBaseMesh メソッドを実装する。これらのメソッドは以下のグループにまとめることができる。

バッファ | GetIndexBuffer
 | GetVertexBuffer
 | LockIndexBuffer
 | LockVertexBuffer
 | UnlockIndexBuffer
 | UnlockVertexBuffer
コピー | CloneMesh
 | CloneMeshFVF
面 | GetNumFaces
情報 | GetDevice
 | GetOptions
レンダリング | DrawSubset
 | GetAttributeTable
頂点 | GetDeclaration
 | GetFVF
 | GetNumVertices

D3DXMesh クラスのメソッドは、以下のグループにまとめることができる。

ロック | LockAttributeBuffer
 | UnlockAttributeBuffer
その他 | ConvertAdjacencyToPointReps
 | ConvertPointRepsToAdjacency
 | GenerateAdjacency
最適化 | Optimize
 | OptimizeInplace


D3DXMesh.ConvertAdjacencyToPointReps

メッシュのポイント表現を生成する。

object.ConvertAdjacencyToPointReps( _
    Adjacency As Any, _
    PointRep As Any)

指定項目

object
D3DXMesh オブジェクトを表すオブジェクト式。
Adjacency
メッシュの面隣接性配列の転送先バッファを表す、Long 値の配列の最初の要素。面隣接性は、配列の配列として格納される。最も内側の配列は、隣接する三角形の 3 つのインデックスで、外側の配列は、メッシュ内の三角形ごとの面隣接性の 1 セットである。この配列のこのサイズは、面の数の最大値に 3 を乗算したものである。「注意」を参照すること。
PointRep
メッシュのポイント表現を表す、Long 値の配列の最初の要素。ポイント表現は、頂点ごとに 1 つの要素を伴うインデックスの配列として格納される。この配列のサイズはメッシュに含まれる頂点の数である。頂点のラベルを変更する必要がない場合は、このパラメータに ByVal 0 を指定できる。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DXERR_INVALIDMESH
E_OUTOFMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

次のサンプル コードは、D3DXBuffer オブジェクトを使用して隣接性情報を渡す方法を示している。

Dim D3DXbAdjacency As D3DXBuffer
Dim PointRep As Any

' このコードでは D3DXbAdjacency および PointRep が正しく
' 初期化されていると仮定している。
Call D3DX8.ConvertPointRepsToAdjacency(ByVal D3DXbAdjacency.GetBufferPointer, PointRep)

注意

ポイント表現は、異なる放線座標、u 座標と v 座標、カラー データなどを使用するのではなく、同じ x 座標、y 座標、z 座標で 2 つの頂点を融合することにより、メッシュの隣接性を記述する方法である。完全になめらかな (しわ、境界、または穴がない) メッシュでは、ポイント表現は冗長である。その場合、ハッシュ テーブルを使用して頂点インデックスを共有するエッジを検索することによって、隣接する三角形を計算することができる。しわおよびテクスチャ境界の場合は、メッシュ内の頂点を構成する共に配置されている頂点グループのハッシュ テーブルで使用する一意の頂点インデックスを指定するために、ポイント表現が必要となる。

参照

D3DXMesh.ConvertPointRepsToAdjacency


D3DXMesh.ConvertPointRepsToAdjacency

Microsoft® DirectX® (.x) ファイルに格納されているポイント表現データを面隣接性情報に変換する。面隣接性情報は、最適化および単純化の操作においてより優れた柔軟性をもたらす。

object.ConvertPointRepsToAdjacency( _
    PointRep As Any, _
    FaceAdjacency As Any)

指定項目

object
D3DXMesh オブジェクトを表すオブジェクト式。
PointRep
メッシュのポイント表現を表す、Long 値の配列の最初の要素。ポイント表現は、頂点ごとに 1 つの要素を伴うインデックスの配列として格納される。この配列のサイズはメッシュに含まれる頂点の数である。頂点のラベルを変更する必要がない場合は、このパラメータに ByVal 0 を指定できる。
FaceAdjacency
メッシュの面隣接性配列の転送先バッファを表す、Long 値の配列の最初の要素。面隣接性は、配列の配列として格納される。最も内側の配列は、隣接する三角形の 3 つのインデックスで、外側の配列は、メッシュ内の三角形ごとの面隣接性の 1 セットである。この配列のこのサイズは、面の数の最大値に 3 を乗算したものである。「注意」を参照すること。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
E_OUTOFMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

ポイント表現は、異なる放線座標、u 座標と v 座標、カラー データなどを使用するのではなく、同じ x 座標、y 座標、z 座標で 2 つの頂点を融合することにより、メッシュの隣接性を記述する方法である。完全になめらかな (しわ、境界、または穴がない) メッシュでは、ポイント表現は冗長である。その場合、ハッシュ テーブルを使用して頂点インデックスを共有するエッジを検索することによって、隣接する三角形を計算することができる。しわおよびテクスチャ境界の場合は、メッシュ内の頂点を構成する共に配置されている頂点グループのハッシュ テーブルで使用する一意の頂点インデックスを指定するために、ポイント表現が必要となる。

次のサンプル コードは、D3DXBuffer オブジェクトを使用して隣接性情報を渡す方法を示している。

Dim d3dxbAdjacency As D3DXBuffer
Dim PointRep As Any

' このコードでは d3dxbAdjacency および PointRep が正しく
' 初期化されていると仮定している。
Call D3DX8.ConvertPointRepsToAdjacency(ByVal PointRep.GetBufferPointer, ByVal d3dxbAdjacency.GetBufferPointer)

参照

D3DXMesh.ConvertAdjacencyToPointReps


D3DXMesh.GenerateAdjacency

Microsoft® DirectX® (.x) ファイルに格納されているポイント表現データを面隣接性情報に変換する。面隣接性情報は、最適化および単純化の操作においてより優れた柔軟性をもたらす。

object.GenerateAdjacency( _
    Epsilon As Single, _
    Adjacency As Any)

指定項目

object
D3DXMesh オブジェクトを表すオブジェクト式。
Epsilon
頂点を結合するときの間隔を示す距離。このパラメータは現在は無視され、Epsilon 0.0 を使用する。
Adjacency
メッシュの面隣接性配列の転送先バッファを表す、Long 値の配列の最初の要素。面隣接性は、配列の配列として格納される。最も内側の配列は、隣接する三角形の 3 つのインデックスで、外側の配列は、メッシュ内の三角形ごとの面隣接性の 1 セットである。この配列のこのサイズは、面の数の最大値に 3 を乗算したものである。「注意」を参照すること。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DXERR_INVALIDDATA
E_OUTOFMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

このメソッドは論理的に頂点を結合するだけで、メッシュに変更を加えるものではない。

次のサンプル コードは、D3DXBuffer オブジェクトを使用して隣接性情報を渡す方法を示している。

Dim d3dxbAdjacency As D3DXBuffer
Dim Eps As Single

' このコードでは d3dxbAdjacency および Eps が正しく
' 初期化されていると仮定している。
Call D3DX8.GenerateAdjacency(Eps, ByVal d3dxbAdjacency.GetBufferPointer)


D3DXMesh.LockAttributeBuffer

属性バッファをロックする。

object.LockAttributeBuffer( _
    Flags As Long) As Long

指定項目

object
D3DXMesh オブジェクトを表すオブジェクト式。
Flags
属性バッファ メモリをロックする方法を指定する、CONST_D3DLOCKFLAGS 列挙で定義される 1 つ以上のロッキング フラグの組み合わせ。

戻り値

属性バッファ データが入力される、Long 値の配列の最初の要素。

エラー コード

失敗した場合はエラーが発生し、Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

参照

D3DXMesh.UnlockAttributeBuffer、D3DXATTRIBUTERANGE


D3DXMesh.Optimize

メッシュの面および頂点の順番変更を制御し、パフォーマンスを最適化する。

object.Optimize( _
    Flags As Any, _
    Adjacency As Any, _
    OptAdj As Any, _
    FaceRemap As Any, _
    BuffVertexRemap As D3DXBuffer, _
    OptMesh As D3DXMesh)

指定項目

object
D3DXMesh オブジェクトを表すオブジェクト式。
Flags
CONST_D3DXMESHOPT 列挙によって定義される 1 つ以上のフラグの組み合わせ。実行する最適化の種類を指定する。

最適化フラグの D3DXMESHOPT_STRIPREORDER および D3DXMESHOPT_VERTEXCACHE はそれぞれ相互に排他的である。

Adjacency
ソース メッシュに含まれる各面の 3 つの隣接面を指定する、1 面あたりの 3 つの Long 値の配列の最初の要素。
OptAdj
最適化されたメッシュの面隣接性配列の転送先バッファを表す、配列の最初の要素。面隣接性は、配列の配列として格納される。最も内側の配列は、隣接する三角形の 3 つのインデックスで、外側の配列は、メッシュ内の三角形ごとの面隣接性の 1 セットである。
FaceRemap
各面の新規インデックスを格納する転送先バッファを表す、配列の最初の要素。
BuffVertexRemap
各頂点の新規インデックスを格納する、D3DXBuffer オブジェクト。
OptMesh
最適化されたメッシュを表す、D3DXMesh オブジェクト。

エラー コード

失敗した場合はエラーが発生し、Err.Number に E_OUTOFMEMORY が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

このメソッドは D3DXBaseMesh.CloneMesh メソッドによく似ているが、メッシュのクローン生成中に最適化を実行できる点が異なる。

出力メッシュは、入力メッシュのすべての作成パラメータを継承する。


D3DXMesh.OptimizeInplace

メッシュの面および頂点の順番変更を制御し、パフォーマンスを最適化する。

object.OptimizeInplace( _
    Flags As Long, _
    AdjacencyIn As Any, _
    AdjacencyOut As Any, _
    FaceRemap As Any, _
    VertexRemapOut As D3DXBuffer)

指定項目

object
D3DXMesh オブジェクトを表すオブジェクト式。
Flags
CONST_D3DXMESHOPT 列挙によって定義される 1 つ以上のフラグの組み合わせ。実行する最適化の種類を指定する。

最適化フラグの D3DXMESHOPT_STRIPREORDER および D3DXMESHOPT_VERTEXCACHE はそれぞれ相互に排他的である。

AdjacencyIn
ソース メッシュに含まれる各面の 3 つの隣接面を指定する、1 面あたりの 3 つの Long 値の配列の最初の要素。
AdjacencyOut
最適化されたメッシュの面隣接性配列の転送先バッファを表す、配列の最初の要素。面隣接性は、配列の配列として格納される。最も内側の配列は、隣接する三角形の 3 つのインデックスで、外側の配列は、メッシュ内の三角形ごとの面隣接性の 1 セットである。
FaceRemap
各面の新規インデックスを格納する転送先バッファを表す、配列の最初の要素。
VertexRemapOut
各頂点の新規インデックスを格納する、D3DXBuffer オブジェクト。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DXERR_CANNOTATTRSORT
E_OUTOFMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

出力メッシュは、入力メッシュのすべての作成パラメータを継承する。

次のサンプル コードは、D3DXBuffer オブジェクトを使用して隣接性情報を渡す方法を示している。

Dim Opts As Long
Dim D3DXbAdjacencyIn As D3DXBuffer
Dim D3DXbAdjacencyOut As Any
Dim FaceRemap As Any
Dim FaceRemap As D3DXBuffer

' このコードでは、すべての引数が
' 正しく初期化されていると仮定している。
Call D3DX8.OptimizeInPlace( Opts, ByVal D3DXbAdjacencyIn.GetBufferPointer, D3DXbAdjacencyOut, _
                                            FaceRemap, FaceRemap )

注 メッシュがほかのメッシュと頂点バッファを共有している場合、D3DXMESHOPT_IGNOREVERTS フラグが Flags パラメータに設定されている場合を除き、このメソッドは失敗する。


D3DXMesh.UnlockAttributeBuffer

属性バッファのロックを解除する。

object.UnlockAttributeBuffer()

指定項目

object
D3DXMesh オブジェクトを表すオブジェクト式。

エラー コード

失敗した場合はエラーが発生し、Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

参照

D3DXMesh.LockAttributeBuffer


D3DXPMesh

アプリケーションは、D3DXPMesh クラスのメソッドを使用してプログレッシブ メッシュ オブジェクトを操作する。プログレッシブ メッシュにより、メッシュ オブジェクトのプログレッシブ リファインが可能となる。

D3DXPMesh クラスは、D3DX8.GeneratePMesh メソッドを呼び出すことにより取得する。

D3DXPMesh クラスは以下に示す D3DXBaseMesh メソッドを継承する。これらのメソッドは、以下のグループにまとめることができる。

バッファ | GetIndexBuffer
 | GetVertexBuffer
 | LockIndexBuffer
 | LockVertexBuffer
 | UnlockIndexBuffer
 | UnlockVertexBuffer
コピー | CloneMesh
 | CloneMeshFVF
面 | GetNumFaces
情報 | GetDevice
 | GetOptions
レンダリング | DrawSubset
 | GetAttributeTable
頂点 | GetDeclaration
 | GetFVF
 | GetNumVertices

D3DXPMesh クラスのメソッドは、以下のグループにまとめることができる。

コピー | ClonePMesh
 | ClonePMeshFVF
面 | GetMaxFaces
 | GetMinFaces
 | SetNumFaces
その他 | GetAdjacency
 | Optimize
頂点 | GetMaxVertices
 | GetMinVertices
 | SetNumVertices


D3DXPMesh.ClonePMesh

宣言子を使用してプログレッシブ メッシュのコピーを作成する。

object.ClonePMesh( _
    Options As Long, _
    Declaration As Any, _
    Device As Direct3DDevice8) As D3DXPMesh

指定項目

object
D3DXPMesh オブジェクトを表すオブジェクト式。
Options
メッシュの作成オプションを指定する、CONST_D3DXMESH 列挙で定義される 1 つ以上のフラグの組み合わせ。
Declaration
出力メッシュに含まれる頂点の頂点フォーマットを記述する宣言子を表す、Long 値の配列の最初の要素。このパラメータは、FVF を直接マップする必要がある。
Device
メッシュに関連付けられているデバイス オブジェクトを表す Direct3DDevice8 オブジェクト。

戻り値

コピーされたプログレッシブ メッシュを表す D3DXPMesh オブジェクト。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
E_OUTOFMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

参照

D3DX8.DeclaratorFromFVF、D3DXBaseMesh.GetDeclaration


D3DXPMesh.ClonePMeshFVF

柔軟な頂点フォーマット (FVF) コードを使用して、プログレッシブ メッシュのコピーを作成する。

object.ClonePMeshFVF( _
    Options As Long, _
    FVF As Long, _
    Device As Direct3DDevice8) As D3DXPMesh

指定項目

object
D3DXPMesh オブジェクトを表すオブジェクト式。
Options
メッシュの作成オプションを指定する、CONST_D3DXMESH 列挙で定義される 1 つ以上のフラグの組み合わせ。
FVF
出力メッシュに含まれる頂点の頂点フォーマットを指定する柔軟な頂点フォーマット フラグの組み合わせ。
Device
メッシュに関連付けられているデバイス オブジェクトを表す Direct3DDevice8 オブジェクト。

戻り値

コピーされたプログレッシブ メッシュを表す D3DXPMesh オブジェクト。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
E_OUTOFMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

ClonePMeshFVF を使用して、プログレッシブ メッシュを 1 つの FVF から別の FVF に変換できる。

参照

D3DX8.FVFFromDeclarator、D3DXBaseMesh.GetFVF


D3DXPMesh.GetAdjacency

メッシュの面隣接性配列を返す。

object.GetAdjacency( _
    AdjacencyOut As Any

指定項目

object
D3DXPMesh オブジェクトを表すオブジェクト式。
AdjacencyOut
返されたメッシュの面隣接性配列。面隣接性は、配列の配列として格納される。最も内側の配列は、隣接する三角形の 3 つのインデックスで、外側の配列は、メッシュ内の三角形ごとの面隣接性の 1 セットである。隣接性配列のサイズは、面の数の最大値に 3 を乗算したものである。

エラー コード

失敗した場合はエラーが発生し、Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

参照

D3DXPMesh.GetMaxFaces


D3DXPMesh.GetMaxFaces

プログレッシブ メッシュがサポートする面の数の最大値を取得する。

object.GetMaxFaces() As Long

指定項目

object
D3DXPMesh オブジェクトを表すオブジェクト式。

戻り値

プログレッシブ メッシュがサポートする面の数の最大値を返す。

エラー コード

失敗した場合はエラーが発生し、Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。


D3DXPMesh.GetMaxVertices

プログレッシブ メッシュがサポートする頂点の数の最大値を取得する。

object.GetMaxVertices() As Long

指定項目

object
D3DXPMesh オブジェクトを表すオブジェクト式。

戻り値

プログレッシブ メッシュがサポートする頂点の数の最大値を返す。

エラー コード

失敗した場合はエラーが発生し、Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。


D3DXPMesh.GetMinFaces

プログレッシブ メッシュがサポートする面の数の最小値を取得する。

object.GetMinFaces() As Long

指定項目

object
D3DXPMesh オブジェクトを表すオブジェクト式。

戻り値

プログレッシブ メッシュがサポートする面の数の最小値を返す。

エラー コード

失敗した場合はエラーが発生し、Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。


D3DXPMesh.GetMinVertices

プログレッシブ メッシュがサポートする頂点の数の最小値を取得する。

object.GetMinVertices() As Long

指定項目

object
D3DXPMesh オブジェクトを表すオブジェクト式。

戻り値

プログレッシブ メッシュがサポートする頂点の数の最小値を返す。

エラー コード

失敗した場合はエラーが発生し、Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。


D3DXPMesh.Optimize

メッシュの面および頂点の順番変更を制御し、パフォーマンスを最適化して、出力メッシュを生成する。

object.Optimize( _
    Flags As Long, _
    AdjacencyOut As Any, _
    FaceRemap As Any, _
    VertexRemapOut As D3DXBuffer) As D3DXMesh

指定項目

object
D3DXPMesh オブジェクトを表すオブジェクト式。
Flags
CONST_D3DXMESHOPT 列挙によって定義される 1 つ以上のフラグの組み合わせ。実行する最適化の種類を指定する。

最適化フラグの D3DXMESHOPT_STRIPREORDER および D3DXMESHOPT_VERTEXCACHE はそれぞれ相互に排他的である。

AdjacencyOut
最適化されたメッシュの面隣接性配列に使用する転送先バッファ。面隣接性は、配列の配列として格納される。最も内側の配列は、隣接する三角形の 3 つのインデックスで、外側の配列は、メッシュ内の三角形ごとの面隣接性の 1 セットである。この配列のサイズは、面の数の最大値に 3 を乗算したものである。
FaceRemap
各面の新規インデックスを格納する、転送先バッファ。
VertexRemapOut
各頂点の新規インデックスを格納する、D3DXBuffer オブジェクト。

戻り値

最適化されたメッシュを表す、D3DXMesh オブジェクト。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
E_OUTOFMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

ClonePMeshFVF を使用して、プログレッシブ メッシュを 1 つの FVF から別の FVF に変換できる。

参照

D3DX8.FVFFromDeclarator、D3DXBaseMesh.GetFVF


D3DXPMesh.SetNumFaces

現在の LOD (Level of Detail) を、指定した面の数にできる限り近づけて設定する。

object.SetNumFaces( _
    Faces As Long)

指定項目

object
D3DXPMesh オブジェクトを表すオブジェクト式。
Faces
面の数を指定する。この値は LOD 変更の希望値を指定する。

エラー コード

失敗した場合はエラーが発生し、Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

面の数が、面の最大値よりも大きい場合、D3DXPMesh.GetMaxFaces が返す面の数の最大値が上限となる。面の数が、面の最小値よりも少ない場合、D3DXPMesh.GetMinFaces が返す面の数の最小値が下限となる。

この呼び出し後は、エッジの折りたたみによって面が 1 つまたは 2 つ増減し、面の数は1 つ少なくなる場合がある。たとえば面の数として 4 および 6 を指定できるときに中間値 5 を指定すると、結果は常に 4 になる。


D3DXPMesh.SetNumVertices

現在の LOD (Level of Detail) を、指定した頂点の数にできる限り近づけて設定する。

object.SetNumVertices( _
    Vertices As Long)

指定項目

object
D3DXPMesh オブジェクトを表すオブジェクト式。
Vertices
頂点の数を指定する。この値は LOD 変更の希望値を指定する。

エラー コード

失敗した場合はエラーが発生し、Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

頂点の数が、頂点の最大値よりも大きい場合、D3DXPMesh.GetMaxVertices が返す頂点の数の最大値が上限となる。頂点の数が、頂点の数の最小値よりも小さい場合、D3DXPMesh.GetMinVertices が返す頂点の数の最小値が下限となる。

この呼び出し後は、エッジの折りたたみによって面が 1 つまたは 2 つ増減し、面の数が1 つ少なくなる場合がある。たとえば面の数として 4 および 6 を指定できるときに中間値 5 を指定すると、結果は常に 4 になる。


D3DXRenderToSurface

D3DXRenderToSurface クラスは、サーフェスへのレンダリングのプロセスを汎用化するために使用する。サーフェスがレンダリング ターゲットではない場合、互換性のあるレンダリング ターゲットが使用され、シーンの終わりで結果がサーフェスにコピーされる。

D3DXRenderToSurface クラスは、D3DX8.CreateRenderToSurface メソッドを呼び出すことによって取得する。

D3DXRenderToSurface クラスのメソッドは、以下のグループにまとめることができる。

情報 | GetDesc
 | GetDevice
レンダリング | BeginScene
 | EndScene


D3DXRenderToSurface.BeginScene

シーンを開始する。

object.BeginScene( _
    Surface As Direct3DSurface8, _
    Viewport As D3DVIEWPORT8)

指定項目

object
D3DXRenderToSurface オブジェクトを表すオブジェクト式。
Surface
レンダリング サーフェスを表す Direct3DSurface8 オブジェクト。
Viewport
シーンのビューポートを記述する D3DVIEWPORT8 型。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DERR_OUTOFVIDEOMEMORY
D3DXERR_INVALIDDATA
E_OUTOFMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

参照

D3DXRenderToSurface.EndScene


D3DXRenderToSurface.EndScene

シーンを終了する。

object.EndScene()

指定項目

object
D3DXRenderToSurface オブジェクトを表すオブジェクト式。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DXERR_INVALIDDATA

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

参照

D3DXRenderToSurface.BeginScene


D3DXRenderToSurface.GetDesc

レンダリング サーフェスのパラメータを取得する。

object.GetDesc( _
    Parameters As D3DXRTS_DESC)

指定項目

object
D3DXRenderToSurface オブジェクトを表すオブジェクト式。
Parameters
レンダリング サーフェスのパラメータを記述する D3DXRTS_DESC 型。

エラー コード

失敗した場合はエラーが発生し、Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。


D3DXRenderToSurface.GetDevice

レンダリング サーフェスに関連付けられている Microsoft® Direct3D® デバイスを取得する。

object.GetDevice() As Direct3DDevice8

指定項目

object
D3DXRenderToSurface オブジェクトを表すオブジェクト式。

戻り値

レンダリング サーフェスに関連付けられている Direct3D デバイス オブジェクトを表す Direct3DDevice8 オブジェクト。

エラー コード

失敗した場合はエラーが発生し、Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。


D3DXSkinMesh

アプリケーションは、D3DXSkinMesh クラスのメソッドを使用してスキン メッシュ オブジェクトを操作する。

D3DXSkinMesh クラスは、次のいずれかのメソッドを呼び出すことにより取得する。

  • D3DX8.CreateSkinMesh
  • D3DX8.CreateSkinMeshFromMesh
  • D3DX8.CreateSkinMeshFVF

Microsoft® DirectX® (.x) ファイル データ オブジェクトからスキン メッシュをロードするには、D3DX8.LoadSkinMeshFromXof メソッドを使用する。

スキニングは、メッシュの異なる複数の頂点を複数のトランスフォーム行列によりトランスフォームするテクニックであり、個々の行列で頂点をトランスフォームした結果をブレンドし、最終的なトランスフォームされた頂点を取得する。

このプロセスは一般にスキニングと呼ばれ、ボーンのスケルトンのアニメーションに基づいて、キャラクタのスキンを定義するメッシュを変形させるために使用される。厳密なアニメーションの最も単純なケースでは、キャラクタ メッシュの異なる複数のパーツをスケルトンの一意な 1 個のボーンに関連付け、そのボーンのトランスフォームを使用して頂点をトランスフォームする。

スキニングを説明するうえで役に立つ用語の意味を次に示す。

  • スキン。変形を利用してレンダリングされる三角形メッシュ。役に立つポーズのキャラクタのモデルであることが多い。
  • ボーン。スキンの 1つ以上の頂点に影響を与えるトランスフォーム行列。
  • スケルトン。スキン メッシュに影響を与えるすべてのボーンからなる階層。
  • ポーズ。ボーン トランスフォームのセット。特定のスキン メッシュに影響を与えるすべてのボーンのトランスフォームを完全に定義する。
  • 初期ポーズ。メッシュがスケルトンに関連付けられたポーズ。スケルトンがこのポーズのときは、変形されたメッシュと元の未変形のメッシュは等しい。
  • ボーン空間トランスフォーム。メッシュを特定のボーンのローカル空間にトランスフォームする。
  • ボーン ウェイト。特定の頂点に対するボーンの影響の度合い。ウェイト 1 は、頂点に影響を与えるボーンがそのボーンだけであることを意味し、0 はそのボーンが頂点に影響を与えないことを意味する。すべての頂点について、1 つの頂点に影響を与えるすべてのボーンのウェイトの合計は 1 になる。

スキニングされたキャラクタは、メッシュのセットと、メッシュの頂点に影響を与えるボーンのセットによって定義される。ボーンはトランスフォーム階層として表現される。メッシュごとに、そのメッシュに影響を与えるすべてのボーンに適用する行列があり、その行列によってメッシュがボーンのローカル座標空間にトランスフォームされる。この行列は、メッシュのボーンのボーン空間トランスフォームである。この行列は、オーサリング プロセスでスケルトンをメッシュに関連付けるときに定義される。

D3DXSkinMesh クラスのメソッドは、以下のグループにまとめることができる。

バッファ | GetIndexBuffer
 | GetVertexBuffer
変換 | ConvertToBlendedMesh
 | ConvertToIndexedBlendedMesh
情報 | GetBoneInfluence
 | GetDevice
 | GetMaxFaceInfluences
 | GetMaxVertexInfluences
 | GetNumBoneInfluences
 | GetNumBones
ロック | LockAttributeBuffer
 | LockIndexBuffer
 | LockVertexBuffer
 | UnlockAttributeBuffer
 | UnlockIndexBuffer
 | UnlockVertexBuffer
その他 | GenerateSkinnedMesh
 | GetOriginalMesh
 | SetBoneInfluence
 | UpdateSkinnedMesh


D3DXSkinMesh.ConvertToBlendedMesh

ブレンドされたメッシュを返す。

object.ConvertToBlendedMesh( _
    Options As Long, _
    AdjacencyIn As Any, _
    AdjacencyOut As Any, _
    RetNumBoneCombinations As Long, _
    RetBoneCombinationTable As D3DXBuffer) As D3DXMesh

指定項目

object
D3DXSkinMesh オブジェクトを表すオブジェクト式。
Options
メッシュに対するオプションを指定する、CONST_D3DXMESH 列挙で定義される 1 つ以上のフラグの組み合わせ。
AdjacencyIn
ソース メッシュに含まれる各面の 3 つの隣接面を指定する、1 面あたりの 3 つの Long 値の配列の最初の要素。「注意」を参照すること。
AdjacencyOut
最適化されたメッシュの面隣接性配列に使用する転送先バッファの最初の要素。面隣接性は、配列の配列として格納される。最も内側の配列は、隣接する三角形の 3 つのインデックスで、外側の配列は、メッシュ内の三角形ごとの面隣接性の 1 セットである。「注意」を参照すること。
RetNumBoneCombinations
エントリの数。
RetBoneCombinationTable
D3DXBONECOMBINATION 型の配列の最初の要素。型のカウントは NumBoneCombinations である。それぞれのボーン組み合わせ表に、一度に描画できる 4 つのボーンが定義される。

戻り値

ブレンドされたメッシュを表す D3DXMesh オブジェクト。

エラー コード

失敗した場合はエラーが発生し、Err.Number に E_OUTOFMEMORY が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

このメソッドは、スキン メッシュを受け取り、ブレンドされたメッシュ (ボーンの影響を受けるメッシュ) に変換する。変換には、Microsoft DirectX® 7.x で利用可能になった Microsoft® Direct3D® 頂点ブレンディング機能を使用する。詳細については、「ジオメトリ ブレンディング」を参照すること。

次のサンプル コードは、D3DXBuffer オブジェクトを使用して隣接性情報を渡す方法を示している。

Dim Opts As Long
Dim D3DXbAdjacencyIn As D3DXBuffer
Dim D3DXbAdjacencyOut As Any
Dim NumBC As Long
Dim RetTable As D3DXBuffer

' このコードでは、すべての引数が
' 正しく初期化されていると仮定している。
Call D3DX8.ConvertToBlendedMesh(Opts, ByVal D3DXbAdjacencyIn.GetBufferPointer, D3DXbAdjacencyOut, _
                                            NumBC, RetTable )


D3DXSkinMesh.ConvertToIndexedBlendedMesh

インデックス付きのブレンドされたメッシュを返す。

object.ConvertToIndexedBlendedMesh( _
    Options As Long, _
    AdjacencyIn As Any, _
    PaletteSize As Long, _
    AdjacencyOut As Any, _
    RetNumBoneCombinations As Long, _
    RetBoneCombinationTable As D3DXBuffer) As D3DXMesh

指定項目

object
D3DXSkinMesh オブジェクトを表すオブジェクト式。
Options
メッシュに対するオプションを指定する、CONST_D3DXMESH 列挙で定義される 1 つ以上のフラグの組み合わせ。
AdjacencyIn
ソース メッシュに含まれる各面の 3 つの隣接面を指定する、1 面あたりの 3 つの Long 値の配列の最初の要素。
PaletteSize
パレット サイズ。
AdjacencyOut
最適化されたメッシュの面隣接性配列に使用する転送先バッファ。面隣接性は、配列の配列として格納される。最も内側の配列は、隣接する三角形の 3 つのインデックスで、外側の配列は、メッシュ内の三角形ごとの面隣接性の 1 セットである。
RetNumBoneCombinations
エントリの数。
RetBoneCombinationTable
D3DXBONECOMBINATION 型の配列の最初の要素。型のカウントは NumBoneCombinations である。それぞれのボーン組み合わせ表に、一度に描画できる 4 つのボーンが定義される。

戻り値

ブレンドされたメッシュを表す D3DXMesh オブジェクト。

エラー コード

失敗した場合はエラーが発生し、Err.Number に E_OUTOFMEMORY が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

このメソッドは、スキン メッシュを受け取り、インデックス付きのブレンドされたメッシュに変換する。変換には、DirectX 8.0 で利用可能になった Direct3D インデックス付き頂点ブレンディング機能を使用する。インデックス付き頂点ブレンディングでは、インデックスを使用して、行列パレットへのインデックスを作成する。詳細については、「ジオメトリ ブレンディング」を参照すること。スキン メッシュからインデックス付きのブレンドされたメッシュに変換すると、単一の描画呼び出しの中でメッシュをレンダリングできる。

次のサンプル コードは、D3DXBuffer オブジェクトを使用して隣接性情報を渡す方法を示している。

Dim Opts As Long
Dim D3DXbAdjacencyIn As D3DXBuffer
Dim PalSize as Long
Dim D3DXbAdjacencyOut As Any
Dim NumBC As Long
Dim RetTable As D3DXBuffer

' このコードでは、すべての引数が
' 正しく初期化されていると仮定している。
Call D3DX8.ConvertToIndexedBlendedMesh(Opts, ByVal D3DXbAdjacencyIn.GetBufferPointer, PalSize, D3DXbAdjacencyOut, _
                                            NumBC, RetTable )


D3DXSkinMesh.GenerateSkinnedMesh

スキニングによってメッシュを生成する。

object.GenerateSkinnedMesh( _
    Options As Long, _
    MinWeight As Single, _
    AdjacencyIn As Any, _
    AdjacencyOut As Any) As D3DXMesh

指定項目

object
D3DXSkinMesh オブジェクトを表すオブジェクト式。
Options
メッシュに対するオプションを指定する、CONST_D3DXMESH 列挙で定義される 1 つ以上のフラグの組み合わせ。
MinWeight
最小ウェイト固定値を設定する。
AdjacencyIn
ソース メッシュに含まれる各面の 3 つの隣接面を指定する、1 面あたりの 3 つの Long 値の配列の最初の要素。「注意」を参照すること。
AdjacencyOut
最適化されたメッシュの面隣接性配列に使用する転送先バッファ。面隣接性は、配列の配列として格納される。最も内側の配列は、隣接する三角形の 3 つのインデックスで、外側の配列は、メッシュ内の三角形ごとの面隣接性の 1 セットである。

戻り値

スキニングによって生成されたメッシュを表す D3DXMesh オブジェクトを返す。

エラー コード

失敗した場合はエラーが発生し、Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

このメソッドでは、すべての行列を指定して各ボーンに適用できる。ジオメトリ ブレンディングは GenerateSkinnedMesh が行うため、Direct3D を使用してジオメトリ ブレンディングを実行する必要はない。特に、このメソッドでは頂点ごとにボーンの影響を 4 つ以上使用できる。

このメソッドにより生成されるメッシュは、スケルトン トランスフォームが変更されるたびに、D3DXSkinMesh.UpdateSkinnedMesh に指定する必要があるメッシュである。

このメソッドはスキン アニメーションに役立つ。

次のサンプル コードは、D3DXBuffer オブジェクトを使用して隣接性情報を渡す方法を示している。

Dim Opts As Long
Dim MinW As Single
Dim D3DXbAdjacencyIn As D3DXBuffer
Dim D3DXbAdjacencyOut As Any

' このコードでは、すべての引数が
' 正しく初期化されていると仮定している。
Call D3DX8.ConvertToIndexedBlendedMesh(Opts, MinW, ByVal D3DXbAdjacencyIn.GetBufferPointer, PalSize, D3DXbAdjacencyOut)


D3DXSkinMesh.GetBoneInfluence

ボーンがスキン メッシュにどのように影響を与えるかを示す値の一覧を返す。

object.GetBoneInfluence( _
    Bone As Long, _
    Vertices As Long, _
    Weights As Single,)

指定項目

object
D3DXSkinMesh オブジェクトを表すオブジェクト式。
Bone
照会するボーン。
Vertices
ボーンが影響を与える頂点の一覧。
Weights
ボーンが影響を与える頂点の一覧に含まれる各頂点に関連付けられたウェイトの一覧。

エラー コード

失敗した場合はエラーが発生し、Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。


D3DXSkinMesh.GetDevice

スキン メッシュに関連付けられているデバイスを取得する。

object.GetDevice() As Direct3DDevice8

指定項目

object
D3DXSkinMesh オブジェクトを表すオブジェクト式。

戻り値

メッシュに関連付けられている Microsoft® Direct3D® デバイスを指定する Direct3DDevice8 オブジェクト。

エラー コード

失敗した場合はエラーが発生し、Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。


D3DXSkinMesh.GetIndexBuffer

インデックス バッファ内のデータを取得する。

object.GetIndexBuffer() As Direct3DIndexBuffer8

指定項目

object
D3DXSkinMesh オブジェクトを表すオブジェクト式。

戻り値

スキン メッシュに関連付けられているインデックス バッファ オブジェクトを表す、Direct3DIndexBuffer8 オブジェクト。

エラー コード

失敗した場合はエラーが発生し、Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。


D3DXSkinMesh.GetMaxFaceInfluences

面の影響の数の最大値を返す。

object.GetMaxFaceInfluences() As Long

指定項目

object
D3DXSkinMesh オブジェクトを表すオブジェクト式。

戻り値

スキン メッシュの任意の 1 面に影響を与える、影響の数の最大値。

エラー コード

失敗した場合はエラーが発生し、Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

各面に n 個のボーンが影響を与える。次に示す図では、1 つの面に 6 つのボーン (面の各頂点に影響を与えるボーンの合計) が影響を与える。


D3DXSkinMesh.GetMaxVertexInfluences

頂点の影響の数の最大値を返す。

object.GetMaxVertexInfluences() As Long

指定項目

object
D3DXSkinMesh オブジェクトを表すオブジェクト式。

戻り値

スキン メッシュの任意の 1 つの頂点に影響を与える、影響の数の最大値。

エラー コード

失敗した場合はエラーが発生し、Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

各頂点に n 個のボーンが影響を与える。このメソッドで 17 という値が返された場合、スキン メッシュの 1 つの頂点に影響を与えるボーンの最大数は 17 である。したがって、その頂点には 17 の別個のウェイトが存在し、ウェイトの合計は 1 になる。


D3DXSkinMesh.GetNumBoneInfluences

特定のボーンに対する影響 (ウェイト) の数を返す。

object.GetNumBoneInfluences( _
    Bone As Long) As Long

指定項目

object
D3DXSkinMesh オブジェクトを表すオブジェクト式。
Bone
照会するボーン。

戻り値

特定のボーンに対するウェイトの数を返す。Bone が無効なボーン数である場合、GetNumBoneInfluences は 0 を返す。

エラー コード

失敗した場合はエラーが発生し、Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。


D3DXSkinMesh.GetNumBones

スキン メッシュに含まれるボーンの数を返す。

object.GetNumBones() As Long

指定項目

object
D3DXSkinMesh オブジェクトを表すオブジェクト式。

戻り値

スキン メッシュに含まれるボーンの数。

エラー コード

失敗した場合はエラーが発生し、Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。


D3DXSkinMesh.GetOriginalMesh

元の (デフォルト) ポーズのスキン メッシュを返す。

object.GetOriginalMesh() As D3DXMesh

指定項目

object
D3DXSkinMesh オブジェクトを表すオブジェクト式。

戻り値

デフォルト ポーズのスキン メッシュを表す D3DXMesh オブジェクト。

エラー コード

失敗した場合はエラーが発生し、Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。


D3DXSkinMesh.GetVertexBuffer

頂点バッファ内のデータを取得する。

object.GetVertexBuffer() As Direct3DVertexBuffer8

指定項目

object
D3DXSkinMesh オブジェクトを表すオブジェクト式。

戻り値

スキン メッシュに関連付けられている頂点バッファ オブジェクトを表す、Direct3DVertexBuffer8 オブジェクト。

エラー コード

失敗した場合はエラーが発生し、Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。


D3DXSkinMesh.LockAttributeBuffer

属性バッファをロックする。

object.LockAttributeBuffer( _
    Flags As Long) As Long

指定項目

object
D3DXSkinMesh オブジェクトを表すオブジェクト式。
Flags
属性バッファ メモリをどのようにロックするかを表す、1 つ以上のロッキング フラグの組み合わせ。設定可能な値は CONST_D3DLOCKFLAGS 列挙で定義されている。

戻り値

属性バッファ データが入力される、Long 値の配列の最初の要素。

エラー コード

失敗した場合はエラーが発生し、Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。


D3DXSkinMesh.LockIndexBuffer

インデックス バッファをロックする。

object.LockIndexBuffer( _
    Flags As Long) As Long

指定項目

object
D3DXSkinMesh オブジェクトを表すオブジェクト式。
Flags
インデックス バッファ メモリをどのようにロックするかを記述する、1 つ以上のロッキング フラグの組み合わせ。設定可能な値は CONST_D3DLOCKFLAGS 列挙で定義されている。

戻り値

返されたインデックス データが入力される、BYTE 値の配列の最初の要素。

エラー コード

失敗した場合はエラーが発生し、Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

インデックス バッファを操作するときは、複数のロック呼び出しを実行できる。ただし、ロック呼び出しの数とロック解除呼び出しの数を一致させる必要がある。現在設定されているインデックス バッファに未処理のロック カウントがある場合、DrawPrimitive 呼び出しは成功しない。

参照

D3DXSkinMesh.UnlockIndexBuffer


D3DXSkinMesh.LockVertexBuffer

頂点バッファをロックする。

object.LockVertexBuffer( _
    Flags As Long) As Long

指定項目

object
D3DXSkinMesh オブジェクトを表すオブジェクト式。
Flags
頂点バッファ メモリをどのようにロックするかを表す、1 つ以上のロッキング フラグの組み合わせ。設定可能な値は CONST_D3DLOCKFLAGS 列挙で定義されている。

戻り値

返された頂点バッファ データが入力される、BYTE 値の配列の最初の要素。

エラー コード

失敗した場合はエラーが発生し、Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

頂点バッファを操作するときは、複数のロック呼び出しを実行できる。ただし、ロック呼び出しの数とロック解除呼び出しの数を一致させる必要がある。現在設定されている頂点バッファに未処理のロック カウントがある場合、DrawPrimitive 呼び出しは成功しない。

参照

D3DXSkinMesh.UnlockVertexBuffer


D3DXSkinMesh.SetBoneInfluence

スキン メッシュに含まれるボーンに対して、ボーンの影響を設定する。

object.SetBoneInfluence( _
    Bone As Long, _
    NumInfluences As Long, _
    Vertices As Long, _
    Weights As Single)

指定項目

object
D3DXSkinMesh オブジェクトを表すオブジェクト式。
Bone
影響を設定するボーン。
NumInfluences
ボーンに対して設定する影響の数。
Vertices
影響 (ウェイト) の設定に使用する頂点の一覧。
Weights
指定された頂点に対して設定するウェイトの一覧。これらの値は、スキン メッシュのスキニング情報をプログラムに基づいて格納するために使用される。

エラー コード

失敗した場合はエラーが発生し、Err.Number に E_OUTOFMEMORY が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

このメソッドは、特定のボーンが特定の頂点にどのように影響を与えるかを指定するしくみを提供する。このメソッドは、メッシュに影響を与える各ボーンに対して呼び出す必要がある。


D3DXSkinMesh.UnlockAttributeBuffer

属性バッファのロックを解除する。

object.UnlockAttributeBuffer()

指定項目

object
D3DXSkinMesh オブジェクトを表すオブジェクト式。

エラー コード

失敗した場合はエラーが発生し、Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

参照

D3DXSkinMesh.LockAttributeBuffer


D3DXSkinMesh.UnlockIndexBuffer

インデックス バッファのロックを解除する。

object.UnlockIndexBuffer()

指定項目

object
D3DXSkinMesh オブジェクトを表すオブジェクト式。

エラー コード

失敗した場合はエラーが発生し、Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

参照

D3DXSkinMesh.LockIndexBuffer


D3DXSkinMesh.UnlockVertexBuffer

頂点バッファのロックを解除する。

object.UnlockVertexBuffer()

指定項目

object
D3DXSkinMesh オブジェクトを表すオブジェクト式。

エラー コード

失敗した場合はエラーが発生し、Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

参照

D3DXSkinMesh.LockVertexBuffer


D3DXSkinMesh.UpdateSkinnedMesh

スキニングされたメッシュを更新する。

object.UpdateSkinnedMesh( _
    BoneTransformsIn As Any, _
    RetMesh As D3DXMesh)

指定項目

object
D3DXSkinMesh オブジェクトを表すオブジェクト式。
BoneTransformsIn
ボーン トランスフォームを表す、D3DMATRIX 型の配列の最初の要素。この配列の長さは、スキン メッシュに含まれるすべてのボーンのカウントである。
RetMesh
スキニングによって生成されたメッシュを格納する D3DXMesh オブジェクト。

注意

このメソッドは、新しいボーン トランスフォームとブレンドされた頂点を更新する。

エラー コード

失敗した場合はエラーが発生し、Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

参照

D3DXSkinMesh.GenerateSkinnedMesh


D3DXSPMesh

アプリケーションは、D3DXSPMesh クラスのメソッドを使用して単純化メッシュ オブジェクトを操作する。単純化メッシュは、指定したメッシュを単純化し、面の数を減らすために使用する。

D3DXSPMesh クラスは、D3DX8.CreateSPMesh メソッドを呼び出すことによって取得する。

D3DXSPMesh クラスのメソッドは、以下のグループにまとめることができる。

コピー | CloneMesh
 | CloneMeshFVF
 | ClonePMesh
 | ClonePMeshFVF
面 | GetMaxFaces
 | GetNumFaces
 | ReduceFaces
情報 | GetDevice
 | GetOptions
頂点 | GetDeclaration
 | GetFVF
 | GetMaxVertices
 | GetNumVertices
 | ReduceVertices


D3DXSPMesh.CloneMesh

宣言子を使用して、メッシュのコピーを作成する。

object.CloneMesh( _
    Options As Long, _
    Declaration As Any, _
    Device As Direct3DDevice8, _
    AdjacencyOut As Any, _
    VertexRemapOut As Any) As D3DXPMesh

指定項目

object
D3DXSPMesh オブジェクトを表すオブジェクト式。
Options
メッシュの作成オプションを指定する、CONST_D3DXMESH 列挙で定義される 1 つ以上のフラグの組み合わせ。
Declaration
出力メッシュに含まれる頂点の頂点フォーマットを記述する宣言子を表す、Long 値の配列の最初の要素。このパラメータは、FVF を直接マップする必要がある。
Device
メッシュに関連付けられているデバイス オブジェクトを表す Direct3DDevice8 オブジェクト。
AdjacencyOut
ソース メッシュに含まれる各面の 3 つの隣接面を指定する、1 面あたりの 3 つの Long 値の配列の最初の要素。
VertexRemapOut
各頂点のインデックスを格納する配列の最初の要素。

戻り値

コピーされたメッシュを表す D3DXPMesh オブジェクト。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
E_OUTOFMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

参照

D3DX8.DeclaratorFromFVF、D3DXSPMesh.GetDeclaration


D3DXSPMesh.CloneMeshFVF

柔軟な頂点フォーマット (FVF) コードを使用してメッシュのコピーを作成する。

object.CloneMeshFVF( _
    Options As Long, _
    FVF As Long, _
    Device As Direct3DDevice8, _
    AdjacencyOut As Any, _
    VertexRemapOut As Any) As D3DXPMesh

指定項目

object
D3DXSPMesh オブジェクトを表すオブジェクト式。
Options
メッシュの作成オプションを指定する、CONST_D3DXMESH 列挙で定義される 1 つ以上のフラグの組み合わせ。
FVF
出力メッシュに含まれる頂点の頂点フォーマットを指定する柔軟な頂点フォーマット フラグの組み合わせ。
Device
メッシュに関連付けられているデバイス オブジェクトを表す Direct3DDevice8 オブジェクト。
AdjacencyOut
ソース メッシュに含まれる各面の 3 つの隣接面を指定する、1 面あたりの 3 つの Long 値の配列の最初の要素。
VertexRemapOut
各頂点のインデックスを格納する配列の最初の要素。

戻り値

コピーされたメッシュを表す D3DXPMesh オブジェクト。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
E_OUTOFMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

CloneMeshFVF を使用して、メッシュを 1 つの FVF から別の FVF に変換できる。

参照

D3DX8.FVFFromDeclarator、D3DXSPMesh.GetFVF


D3DXSPMesh.ClonePMesh

宣言子を使用してプログレッシブ メッシュのコピーを作成する。

object.ClonePMesh( _
    Options As Long, _
    Declaration As Any, _
    Device As Direct3DDevice8, _
    VertexRemapOut As Any) As D3DXPMesh

指定項目

object
D3DXSPMesh オブジェクトを表すオブジェクト式。
Options
メッシュの作成オプションを指定する、CONST_D3DXMESH 列挙で定義される 1 つ以上のフラグの組み合わせ。
Declaration
出力メッシュに含まれる頂点の頂点フォーマットを記述する宣言子を表す、Long 値の配列の最初の要素。このパラメータは、FVF を直接マップする必要がある。
Device
メッシュに関連付けられているデバイス オブジェクトを表す Direct3DDevice8 オブジェクト。
VertexRemapOut
各頂点のインデックスを格納する配列の最初の要素。

戻り値

コピーされたプログレッシブ メッシュを表す D3DXPMesh オブジェクト。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DXERR_CANNOTATTRSORT
E_OUTOFMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

参照

D3DX8.DeclaratorFromFVF、D3DXSPMesh.GetDeclaration


D3DXSPMesh.ClonePMeshFVF

柔軟な頂点フォーマット (FVF) コードを使用して、プログレッシブ メッシュのコピーを作成する。

object.ClonePMeshFVF( _
    Options As Long, _
    FVF As Long, _
    Device As Direct3DDevice8, _
    VertexRemapOut As Any) As D3DXPMesh

指定項目

object
D3DXSPMesh オブジェクトを表すオブジェクト式。
Options
メッシュの作成オプションを指定する、CONST_D3DXMESH 列挙で定義される 1 つ以上のフラグの組み合わせ。
FVF
出力メッシュに含まれる頂点の頂点フォーマットを指定する柔軟な頂点フォーマット フラグの組み合わせ。
Device
メッシュに関連付けられているデバイス オブジェクトを表す Direct3DDevice8 オブジェクト。
VertexRemapOut
各頂点のインデックスを格納する配列の最初の要素。

戻り値

コピーされたプログレッシブ メッシュを表す D3DXPMesh オブジェクト。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DERR_OUTOFVIDEOMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

ClonePMeshFVF を使用して、プログレッシブ メッシュを 1 つの FVF から別の FVF に変換できる。

参照

D3DX8.FVFFromDeclarator、D3DXSPMesh.GetFVF


D3DXSPMesh.GetDeclaration

メッシュに含まれる頂点を記述する宣言を取得する。

object.GetDeclaration( _
    Declaration As Long)

指定項目

object
D3DXSPMesh オブジェクトを表すオブジェクト式。
Declaration
照会されたメッシュに含まれる頂点の頂点フォーマットを記述する配列の最初の要素。この宣言子の配列の上限は MAX_FVF_DECL_SIZE で、宣言子を 15 Long 値の最大数に制限する。

エラー コード

失敗した場合はエラーが発生し、Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

参照

D3DXSPMesh.GetFVF


D3DXSPMesh.GetDevice

単純化メッシュに関連付けられているデバイス オブジェクトを取得する。

object.GetDevice() As Direct3DDevice8

指定項目

object
D3DXSPMesh オブジェクトを表すオブジェクト式。

戻り値

単純化メッシュに関連付けられている Microsoft® Direct3D® デバイスを指定する、Direct3DDevice8 オブジェクト。

エラー コード

失敗した場合はエラーが発生し、Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。


D3DXSPMesh.GetFVF

単純化メッシュに含まれる頂点の柔軟な頂点フォーマットを取得する。

object.GetFVF() As Long

指定項目

object
D3DXSPMesh オブジェクトを表すオブジェクト式。

戻り値

単純化メッシュに含まれる頂点の頂点フォーマットを記述する、柔軟な頂点フォーマット フラグの組み合わせ。

エラー コード

失敗した場合はエラーが発生し、Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

参照

D3DXSPMesh.GetDeclaration


D3DXSPMesh.GetMaxFaces

単純化メッシュがサポートする面の数の最大値を取得する。

object.GetMaxFaces() As Long

指定項目

object
D3DXSPMesh オブジェクトを表すオブジェクト式。

戻り値

元のメッシュに含まれる面の最大数を返す。

エラー コード

失敗した場合はエラーが発生し、Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。


D3DXSPMesh.GetMaxVertices

単純化メッシュがサポートする頂点の数の最大値を取得する。

object.GetMaxVertices() As Long

指定項目

object
D3DXSPMesh オブジェクトを表すオブジェクト式。

戻り値

元のメッシュに含まれる頂点の最大数を返す。

エラー コード

失敗した場合はエラーが発生し、Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。


D3DXSPMesh.GetNumFaces

単純化メッシュに含まれる面の数を取得する。

object.GetNumFaces() As Long

指定項目

object
D3DXSPMesh オブジェクトを表すオブジェクト式。

戻り値

単純化メッシュに含まれる面の数を返す。

エラー コード

失敗した場合はエラーが発生し、Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。


D3DXSPMesh.GetNumVertices

単純化メッシュに含まれる頂点の数を取得する。

object.GetNumVertices() As Long

指定項目

object
D3DXSPMesh オブジェクトを表すオブジェクト式。

戻り値

単純化メッシュに含まれる頂点の数を返す。

エラー コード

失敗した場合はエラーが発生し、Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。


D3DXSPMesh.GetOptions

この単純化メッシュの作成時に有効になっているメッシュ オプションを取得する。

object.GetOptions() As Long

指定項目

object
D3DXSPMesh オブジェクトを表すオブジェクト式。

戻り値

このメッシュの作成時に有効になっているオプションを示す、CONST_D3DXMESH 列挙で定義される 1 つ以上のフラグの組み合わせを返す。

エラー コード

失敗した場合はエラーが発生し、Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。


D3DXSPMesh.ReduceFaces

単純化メッシュに含まれる面の数を減らす。

object.ReduceFaces( _
    Faces As Long)

指定項目

object
D3DXSPMesh オブジェクトを表すオブジェクト式。
Faces
プリミティブ カウントを減らした後の面の数。

エラー コード

失敗した場合はエラーが発生し、Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

このメソッドは、エッジの折りたたみを行い、Faces で指定した値までプリミティブの数を減らす。特定の制限があるため、メッシュを要求された値まで常に減らせるわけではない。


D3DXSPMesh.ReduceVertices

単純化メッシュに含まれる頂点の数を減らす。

object.ReduceVertices( _
    Vertices As Long)

指定項目

object
D3DXSPMesh オブジェクトを表すオブジェクト式。
Vertices
プリミティブ カウントを減らした後の頂点の数。

エラー コード

失敗した場合はエラーが発生し、Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

このメソッドは、エッジの折りたたみを行い、Vertices で指定した値までプリミティブの数を減らす。特定の制限があるため、メッシュを要求された値まで常に減らせるわけではない。


D3DXSprite

D3DXSprite クラスは、Microsoft® Direct3D® を使用してスプライトを描画するプロセスを単純化するメソッドのセットを提供する。

D3DXSprite クラスは、D3DX8.CreateSprite メソッドを呼び出すことによって取得する。

D3DXSprite クラスのメソッドは、以下のグループにまとめることができる。

描画 | Begin
 | Draw
 | DrawTransform
 | End
情報 | GetDevice


D3DXSprite.Begin

スプライトを描画できるようにデバイスを準備する。

object.Begin()

指定項目

object
D3DXSprite オブジェクトを表すオブジェクト式。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DXERR_INVALIDDATA

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

Begin の呼び出しは省略可能である。Begin/End シーケンスの外で呼び出された場合、描画関数は内部で Begin および End を呼び出す。余分なオーバーヘッドを避けるため、このメソッドは、複数の描画関数を連続して呼び出す場合に使用する。

Direct3DDevice8.BeginScene または D3DXRenderToSurface.BeginScene の代わりとして D3DXSprite.Begin を使用することはできない。

参照

D3DXSprite.End


D3DXSprite.Draw

スクリーン空間に単純なスプライトを描画する。

object.Draw( _
    SrcTexture As Direct3DTexture8, _
    SrcRect As Any, _
    Scaling As D3DVECTOR2, _
    RotationCenter As D3DVECTOR2, _
    Rotation As Single, _
    Translation As D3DVECTOR2, _
    Color As Long)

指定項目

object
D3DXSprite オブジェクトを表すオブジェクト式。
SrcTexture
スプライトに使用するソース イメージを表す Direct3DTexture8 オブジェクト。
SrcRect
ソース テクスチャのどの部分をスプライトに使用するかを示す RECT 型。このパラメータを ByVal 0 にすると、ソース イメージ全体がスプライトに使用される。ただし、ソース イメージの部分的な矩形を指定することもできる。この RECT 型の左と上および右と下のパラメータを入れ替えると、x と y のミラーリングを簡単に指定できる。
Scaling
スケーリング ベクトルである D3DVECTOR2 型。
RotationCenter
回転の中心を識別する D3DVECTOR2 型。
Rotation
回転を指定する値。
Translation
平行移動を表す D3DVECTOR2 型。
Color
カラーを記述する値。この値によりカラー チャネルとアルファ チャネルが乗算される。

エラー コード

失敗した場合はエラーが発生し、Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

D3DXSprite.Begin が呼び出されなかった場合、このメソッドは Begin と D3DXSprite.End を内部的に呼び出す。D3DXSprite.Draw または D3DXSprite.DrawTransform、あるいはその両方を引き続き呼び出すときは、Draw および DrawTransform が毎回内部で Begin および End を呼び出すことによる余分なオーバーヘッドを避けるため、必ず Begin を呼び出すこと。

参照

D3DXSprite.DrawTransform


D3DXSprite.DrawTransform

指定した行列によってトランスフォームしたスプライトを描画するためのしくみを提供する。

object.DrawTransform( _
    SrcTexture As Direct3DTexture8, _
    SrcRect As Any, _
    TransformMatrix As D3DMATRIX, _
    Color As Long)

指定項目

object
D3DXSprite オブジェクトを表すオブジェクト式。
SrcTexture
スプライトに使用するソース イメージを表す Direct3DTexture8 オブジェクト。
SrcRect
ソース テクスチャのどの部分をスプライトに使用するかを示す RECT 型。このパラメータを ByVal 0 にすると、ソース イメージ全体がスプライトに使用される。ただし、ソース イメージの部分的な矩形を指定することもできる。この RECT 型の左と上および右と下のパラメータを入れ替えると、x と y のミラーリングを簡単に指定できる。

トランスフォームの前に、スプライトのサイズが SrcRect により左上隅を始点 (0,0) として定義される。

TransformMatrix
適用するトランスフォームを指定する D3DMATRIX 型。
Color
カラーを表す値。この値によりカラー チャネルとアルファ チャネルが乗算される。

エラー コード

失敗した場合はエラーが発生し、Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

D3DXSprite.Begin が呼び出されなかった場合、このメソッドは Begin と D3DXSprite.End を内部的に呼び出す。D3DXSprite.Draw または D3DXSprite.DrawTransform、あるいはその両方を引き続き呼び出すときは、Draw および DrawTransform が毎回内部で Begin および End を呼び出すことによる余分なオーバーヘッドを避けるため、必ず Begin を呼び出すこと。

参照

D3DXSprite.Draw


D3DXSprite.End

D3DXSprite.Begin が呼び出された時点のデバイスの状態を復元する。

object.End()

指定項目

object
D3DXSprite オブジェクトを表すオブジェクト式。

エラー コード

失敗した場合はエラーが発生し、Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

Direct3DDevice8.EndScene または D3DXRenderToSurface.EndScene の代わりとして D3DXSprite.End を使用することはできない。

参照

D3DXSprite.Begin


D3DXSprite.GetDevice

スプライト オブジェクトに関連付けられている Microsoft® Direct3D® デバイスを取得する。

object.GetDevice() As Direct3DDevice8

指定項目

object
D3DXSprite オブジェクトを表すオブジェクト式。

戻り値

スプライト オブジェクトに関連付けられているデバイス オブジェクトを表す Direct3DDevice8 オブジェクト。

エラー コード

失敗した場合はエラーが発生し、Err.Number に D3DERR_INVALIDCALL が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。


関数

ここでは、Direct3DX を使用する場合に実装する必要がある関数のリファレンス情報を記述する。以下の関数が実装される。

  • コピー関数
  • 算術関数


コピー関数

Microsoft® Direct3DX® ユーティリティ ライブラリが提供するコピー処理ライブラリを使用して、頂点配列、インデックス配列、およびメッシュ オブジェクトに関連付けられた頂点バッファおよびインデックス バッファ間でデータを簡単にコピーできる。

メッシュ バファ | D3DXMeshIndexBuffer8GetData
 | D3DXMeshIndexBuffer8SetData
 | D3DXMeshVertexBuffer8GetData
 | D3DXMeshVertexBuffer8SetData
メモリ | DXCopyMemory


D3DXMeshIndexBuffer8GetData

メッシュ オブジェクトにアタッチされた頂点バッファのインデックスをインデックス配列にコピーする。

D3DXMeshIndexBuffer8GetData( _
    D3DXMeshobj As Unknown, _
    Offset As Long, _
    Size As Long, _
    Flags As Long, _
    Data As Any) As Long

パラメータ

D3DXMeshobj
読み出す頂点バッファを含む D3DXMesh オブジェクトになるオブジェクト。
Offset
バッファの先頭からデータ読み出しの開始位置へのオフセット (バイト単位)。
Size
バッファのサイズ (バイト単位)。
Flags
実行するロックの種類を記述する CONST_D3DLOCKFLAGS 列挙によって定義される、1 つまたは複数の有効なロッキング フラグの組み合わせ。
Data
読み出したデータが格納されるメモリ。「注意」を参照すること。

戻り値

成功した場合は、D3D_OK を返す。

失敗した場合は、次のいずれかの値を返す。

D3DERR_INVALIDCALL
E_INVALIDARG

エラー コード

この関数では、Err.Number は設定されていない。

注意

次のコードは、この関数の一般的な使用方法を示している。

Dim IndexArray(9) As Long
Dim Mesh As D3DXMesh
Dim hr As Long

'次のコードでは、Mesh が適切に初期化されていると仮定している。
hr = D3DXMeshIndexBuffer8GetData(Mesh, 0, (Len(IndexArray(0)) * 10), _
                                  0, IndexArray(0))

参照

D3DXMeshIndexBuffer8SetData


D3DXMeshIndexBuffer8SetData

メッシュ オブジェクトにアタッチされたインデックス バッファにインデックスの配列のインデックスをコピーする。

D3DXMeshIndexBuffer8SetData( _
    D3DXMeshobj As Unknown, _
    Offset As Long, _
    Size As Long, _
    Flags As Long, _
    Data As Any) As Long

パラメータ

D3DXMeshobj
設定するインデックス バッファを含む D3DXMesh オブジェクトになるオブジェクト。
Offset
インデックス バッファの先頭からデータの設定位置へのオフセット (バイト単位)。
Size
バッファのサイズ (バイト単位)。
Flags
実行するロックの種類を記述する CONST_D3DLOCKFLAGS 列挙によって定義される 1 つ以上の有効なロッキング フラグの組み合わせ。
Data
インデックス バッファの設定に使用されるインデックス配列の先頭要素。「注意」を参照すること。

戻り値

成功した場合は、D3D_OK を返す。

失敗した場合は、次のいずれかの値を返す。

D3DERR_INVALIDCALL
E_INVALIDARG

エラー コード

この関数では、Err.Number は設定されていない。

注意

次のコードは、この関数の一般的な使用方法を示している。

Dim IndexArray(9) As Long
Dim Mesh As D3DXMesh
Dim hr As Long

'次のコードでは、Mesh が適切に初期化されていると仮定している。
hr = D3DXMeshIndexBuffer8SetData(Mesh, 0, (Len(IndexArray(0)) * 10), _
                                  0, IndexArray(0))

参照

D3DXMeshIndexBuffer8GetData


D3DXMeshVertexBuffer8GetData

メッシュ オブジェクトにアタッチされた頂点バッファの頂点を頂点配列にコピーする。

D3DXMeshVertexBuffer8GetData( _
    D3DXMeshobj As Unknown, _
    Offset As Long, _
    Size As Long, _
    Flags As Long, _
    Data As Any) As Long

パラメータ

D3DXMeshobj
読み出す頂点バッファを含む D3DXMesh オブジェクトになるオブジェクト。
Offset
バッファの先頭からデータ読み出し位置へのオフセット (バイト単位)。
Size
バッファのサイズ (バイト単位)。
Flags
実行するロックの種類を記述する CONST_D3DLOCKFLAGS 列挙によって定義される 1 つ以上の有効なロッキング フラグの組み合わせ。
Data
読み出されたデータが格納される、頂点の配列の先頭要素。「注意」を参照すること。

戻り値

成功した場合は、D3D_OK を返す。

失敗した場合は、次のいずれかの値を返す。

D3DERR_INVALIDCALL
E_INVALIDARG

エラー コード

この関数では、Err.Number は設定されていない。

注意

次のコードは、この関数の一般的な使用方法を示している。

Dim VertArray(9) As D3DVERTEX
Dim Mesh As D3DXMesh
Dim hr As Long

'次のコードでは、Mesh が適切に初期化されていると仮定している。
hr = D3DXMeshVertexBuffer8GetData(Mesh, 0, (Len(VertArray(0)) * 10), _
                                  0, VertArray(0))

参照

D3DXMeshVertexBuffer8SetData


D3DXMeshVertexBuffer8SetData

メッシュ オブジェクトにアタッチされた頂点バッファに頂点配列の頂点をコピーする。

D3DXMeshVertexBuffer8SetData( _
    D3DXMeshobj As Unknown, _
    Offset As Long, _
    Size As Long, _
    Flags As Long, _
    Data As Any) As Long

パラメータ

D3DXMeshobj
設定する頂点バッファを含む D3DXMesh オブジェクトになるオブジェクト。
Offset
バッファの先頭からデータの設定位置までのオフセット (オフセット)。
Size
バッファのサイズ (バイト単位)。
Flags
実行するロックの種類を記述する CONST_D3DLOCKFLAGS 列挙によって定義される 1 つ以上の有効なロッキング フラグの組み合わせ。
Data
頂点バッファの設定に使用される頂点の配列の先頭要素。「注意」を参照すること。

戻り値

成功した場合は、D3D_OK を返す。

失敗した場合は、次のいずれかの値を返す。

D3DERR_INVALIDCALL
E_INVALIDARG

エラー コード

この関数では、Err.Number は設定されていない。

注意

次のコードは、この関数の一般的な使用方法を示している。

Dim VertArray(9) As D3DVERTEX
Dim Mesh As D3DXMesh
Dim hr As Long

'次のコードでは、Mesh が適切に初期化されていると仮定している。
hr = D3DXMeshVertexBuffer8SetData(Mesh, 0, (Len(VertArray(0)) * 10), _
                                  0, VertArray(0))

参照

D3DXMeshVertexBuffer8GetData


DXCopyMemory

DXCopyMemory( _
    Dest As Any, _
    Src As Any, _
    Size As Long) As Long

パラメータ

Dest
データのコピー先メモリ。「注意」を参照すること。
Src
データのコピー元メモリ。「注意」を参照すること。
Size
コピーするデータのサイズ (バイト単位)。

戻り値

成功した場合は、D3D_OK を返す。

失敗した場合は、次のいずれかの値を返す。

D3DERR_INVALIDCALL
E_INVALIDARG

エラー コード

この関数では、Err.Number は設定されていない。

注意

Dest および Src には、次の値を指定できる。型、配列の先頭要素、D3DXBuffer.GetBufferPointer が返すポインタ、Direct3DIndexBuffer8.Lock または Direct3DVertexBuffer8.Lock のいずれかが返すポインタ。


算術関数

Direct3DX ユーティリティ ライブラリで提供される算術ライブラリには、基本的な数値演算と複雑な 3D 算術演算を行うための関数が用意されている。

3D 数値演算関数は、以下のグループにまとめることができる。

色 | D3DXColorAdd
 | D3DXColorAdjustContrast
 | D3DXColorAdjustSaturation
 | D3DXColorLerp
 | D3DXColorModulate
 | D3DXColorNegative
 | D3DXColorScale
 | D3DXColorSubtract
平面 | D3DXPlaneDot
 | D3DXPlaneDotCoord
 | D3DXPlaneDotNormal
 | D3DXPlaneFromPointNormal
 | D3DXPlaneFromPoints
 | D3DXPlaneIntersectLine
 | D3DXPlaneNormalize
 | D3DXPlaneTransform
クオータニオン | D3DXQuaternionBaryCentric
 | D3DXQuaternionConjugate
 | D3DXQuaternionDot
 | D3DXQuaternionExp
 | D3DXQuaternionIdentity
 | D3DXQuaternionInverse
 | D3DXQuaternionIsIdentity
 | D3DXQuaternionLength
 | D3DXQuaternionLengthSq
 | D3DXQuaternionLn
 | D3DXQuaternionMultiply
 | D3DXQuaternionNormalize
 | D3DXQuaternionRotationAxis
 | D3DXQuaternionRotationMatrix
 | D3DXQuaternionRotationYawPitchRoll
 | D3DXQuaternionSlerp
 | D3DXQuaternionSquad
 | D3DXQuaternionToAxisAngle
2D ベクトル | D3DXVec2Add
 | D3DXVec2BaryCentric
 | D3DXVec2CatmullRom
 | D3DXVec2CCW
 | D3DXVec2Dot
 | D3DXVec2Hermite
 | D3DXVec2Length
 | D3DXVec2LengthSq
 | D3DXVec2Lerp
 | D3DXVec2Maximize
 | D3DXVec2Minimize
 | D3DXVec2Normalize
 | D3DXVec2Scale
 | D3DXVec2Subtract
 | D3DXVec2Transform
 | D3DXVec2TransformCoord
 | D3DXVec2TransformNormal
3D ベクトル | D3DXVec3Add
 | D3DXVec3BaryCentric
 | D3DXVec3CatmullRom
 | D3DXVec3Cross
 | D3DXVec3Dot
 | D3DXVec3Hermite
 | D3DXVec3Length
 | D3DXVec3LengthSq
 | D3DXVec3Lerp
 | D3DXVec3Maximize
 | D3DXVec3Minimize
 | D3DXVec3Normalize
 | D3DXVec3Project
 | D3DXVec3Scale
 | D3DXVec3Subtract
 | D3DXVec3Transform
 | D3DXVec3TransformCoord
 | D3DXVec3TransformNormal
 | D3DXVec3Unproject
4D 行列 | D3DXMatrixAffineTransformation
 | D3DXMatrixfDeterminant
 | D3DXMatrixIdentity
 | D3DXMatrixInverse
 | D3DXMatrixIsIdentity
 | D3DXMatrixLookAtLH
 | D3DXMatrixLookAtRH
 | D3DXMatrixMultiply
 | D3DXMatrixOrthoLH
 | D3DXMatrixOrthoRH
 | D3DXMatrixOrthoOffCenterLH
 | D3DXMatrixOrthoOffCenterRH
 | D3DXMatrixPerspectiveFovLH
 | D3DXMatrixPerspectiveFovRH
 | D3DXMatrixPerspectiveLH
 | D3DXMatrixPerspectiveRH
 | D3DXMatrixPerspectiveOffCenterLH
 | D3DXMatrixPerspectiveOffCenterRH
 | D3DXMatrixReflect
 | D3DXMatrixRotationAxis
 | D3DXMatrixRotationQuaternion
 | D3DXMatrixRotationX
 | D3DXMatrixRotationY
 | D3DXMatrixRotationYawPitchRoll
 | D3DXMatrixRotationZ
 | D3DXMatrixScaling
 | D3DXMatrixShadow
 | D3DXMatrixTransformation
 | D3DXMatrixTranslation
 | D3DXMatrixTranspose
4D ベクトル | D3DXVec4Add
 | D3DXVec4BaryCentric
 | D3DXVec4CatmullRom
 | D3DXVec4Cross
 | D3DXVec4Dot
 | D3DXVec4Hermite
 | D3DXVec4Length
 | D3DXVec4LengthSq
 | D3DXVec4Lerp
 | D3DXVec4Maximize
 | D3DXVec4Minimize
 | D3DXVec4Normalize
 | D3DXVec4Scale
 | D3DXVec4Subtract
 | D3DXVec4Transform


D3DXColorAdd

2 つのカラー値を加算して、新しいカラー値を作成する。

D3DXColorAdd( _
    COut As D3DCOLORVALUE, _
    C1 As D3DCOLORVALUE, _
    C2 As D3DCOLORVALUE)

パラメータ

COut
演算結果である 2 つのカラー値の和が格納される D3DCOLORVALUE 型。
C1
処理の基になる D3DCOLORVALUE 型。
C2
処理の基になる D3DCOLORVALUE 型。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DERR_OUTOFVIDEOMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

参照

D3DXColorModulate、D3DXColorSubtract


D3DXColorAdjustContrast

色のコントラスト値を調整する。

D3DXColorAdjustContrast( _
    COut As D3DCOLORVALUE, _
    C1 As D3DCOLORVALUE, _
    c As Single)

パラメータ

COut
演算結果であるコントラスト調整の結果が格納される D3DCOLORVALUE 型。
C1
処理の基になる D3DCOLORVALUE 型。
c
コントラスト値。このパラメータは、50% グレーと色 C1 の間を線形補間する。c の値に制限はない。このパラメータが 0 の場合、返される色は 50% グレーである。このパラメータが 1 の場合、返される色は元の色である。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DERR_OUTOFVIDEOMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

次の例で示すように、この関数は 50% グレーと指定コントラスト値の間で D3DCOLORVALUE 型の赤 (red)、緑 (green)、および青 (blue) の色成分を補間する。

    Cout.r = 0.5 + c * (C1.r - 0.5)

c が 0 より大きく 1 より小さい場合、コントラストは小さくなる。c が 1 より大きい場合、コントラストは大きくなる。

参照

D3DXColorAdjustSaturation


D3DXColorAdjustSaturation

色の彩度値を調整する。

D3DXColorAdjustSaturation( _
    COut As D3DCOLORVALUE, _
    C1 As D3DCOLORVALUE, _
    s As Single)

パラメータ

COut
演算結果である彩度調整の結果が格納される D3DCOLORVALUE 型。
C1
処理の基になる D3DCOLORVALUE 型。
s
彩度値。このパラメータは、グレー スケールに変換された色と元の色 C1 の間を線形補間する。s の値に制限はない。s が 0 の場合、返される色はグレー スケールの色である。s が 1 の場合、返される色は元の色である。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DERR_OUTOFVIDEOMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

次に示す例のように、この関数は非飽和色とある色の間で D3DCOLORVALUE 型の赤 (red)、緑 (green)、青 (blue) の色成分を補間する。

    ' 輝度に対する各成分の係数の適切な値。
    ' ITU-R 勧告 BT.709 に記載された NTSC 標準に基づく。
    Dim Grey As Long
    Grey = C1.r * 0.2125 + C1.g * 0.7154 + C1.b * 0.0721

    COut.r = Grey + s * (C1.r - Grey)

s が 0 より大きく 1 より小さい場合、彩度は小さくなる。s が 1 より大きい場合、彩度は大きくなる。

グレー スケール色は次のようにして算出される : r = g = b = 0.2125*r + 0.7154*g + 0.0721*b

参照

D3DXColorAdjustContrast


D3DXColorLerp

線形補間を使ってカラー値を作成する。

D3DXColorLerp( _
    COut As D3DCOLORVALUE, _
    C1 As D3DCOLORVALUE, _
    C2 As D3DCOLORVALUE, _
    s As Single)

パラメータ

COut
演算結果である線形補間の結果が格納される D3DCOLORVALUE 型。
C1
処理の基になる D3DCOLORVALUE 型。
C2
処理の基になる D3DCOLORVALUE 型。
s
色 C1 と C2 を 4D ベクトルとして処理し、これらの間を線形補間するパラメータ。s の値に制限はない。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DERR_OUTOFVIDEOMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

次に示す例のように、この関数は 2 つの色の間で D3DCOLORVALUE 型の赤 (red)、緑 (green)、青 (blue) の色成分とアルファ成分を補間する。

    COut.r = .C1.r + s * (C2.r - C1.r)

色 A と B の間を線形補間し、s が 0 の場合、結果の色は A になる。s が 1 の場合、結果の色は B になる。

参照

D3DXColorModulate、D3DXColorNegative、D3DXColorScale


D3DXColorModulate

2 つの色をブレンドする。

D3DXColorModulate( _
    COut As D3DCOLORVALUE, _
    C1 As D3DCOLORVALUE, _
    C2 As D3DCOLORVALUE)

パラメータ

COut
演算結果であるブレンディング処理の結果が格納される D3DCOLORVALUE 型。
C1
処理の基になる D3DCOLORVALUE 型。
C2
処理の基になる D3DCOLORVALUE 型。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DERR_OUTOFVIDEOMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

次の例に示すように、この関数は対応する 2 つの色成分の積を求めて 2 種類のカラーをブレンドする。

    Cout.r = C1.r * C2.r

参照

D3DXColorLerp、D3DXColorNegative、D3DXColorScale


D3DXColorNegative

あるカラー値に対する負のカラー値を作成する。

D3DXColorNegative( _
    COut As D3DCOLORVALUE, _
    C As D3DCOLORVALUE)

パラメータ

COut
演算結果である、指定したカラー値に対する負のカラー値が格納される D3DCOLORVALUE 型。
C
処理の基になる D3DCOLORVALUE 型。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DERR_OUTOFVIDEOMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

次の例に示すように、この関数は D3DCOLORVALUE 型の色成分から 1.0 を減算することで、負のカラー値を返す。

    COut.r = 1.0 - C.r

参照

D3DXColorLerp、D3DXColorModulate、D3DXColorScale


D3DXColorScale

カラー値をスケーリングする。

D3DXColorScale( _
    COut As D3DCOLORVALUE, _
    C1 As D3DCOLORVALUE, _
    s As Single)

パラメータ

COut
演算結果であるスケーリングされたカラー値が格納される D3DCOLORVALUE 型。
C1
処理の基になる D3DCOLORVALUE 型。
s
スケーリング係数。色を 4D ベクトルのように扱って、スケーリングする。s の値に制限はない。s が 1 の場合、結果の色は元の色である。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DERR_OUTOFVIDEOMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

次の例に示すように、この関数は、D3DCOLORVALUE 型の色成分に指定されたスケーリング係数を積算することで、スケーリングしたカラー値を算出する。

    Cout.r = C1.r * s

参照

D3DXColorLerp、D3DXColorModulate、D3DXColorNegative


D3DXColorSubtract

2 つのカラー値を減算して、新しいカラー値を作成する。

D3DXColorSubtract( _
    COut As D3DCOLORVALUE, _
    C1 As D3DCOLORVALUE, _
    C2 As D3DCOLORVALUE)

パラメータ

COut
演算結果である 2 つのカラー値の差が格納される D3DCOLORVALUE 型。
C1
処理の基になる D3DCOLORVALUE 型。
C2
処理の基になる D3DCOLORVALUE 型。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DERR_OUTOFVIDEOMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

参照

D3DXColorAdd


D3DXMatrixAffineTransformation

アフィン変換行列を作成する。

D3DXMatrixAffineTransformation( _
    MOut As D3DMATRIX, _
    Scaling As Single, _
    VRotationCenter As D3DVECTOR, _
    QRotation As D3DQUATERNION, _
    VTranslation As D3DVECTOR)

パラメータ

MOut
演算結果であるアフィン変換行列が格納される D3DMATRIX 型。
Scaling
スケーリング係数。
VRotationCenter
回転の中心を識別するポイントを表す D3DVECTOR 型。この引数が空の D3DVECTOR 型の場合は、回転しないと見なされる。
QRotation
回転を指定する D3DQUATERNION 型。この引数が空の D3DQUATERNION 型の場合は、回転しないと見なされる。
VTranslation
平行移動を表す D3DVECTOR 型。この引数が空の D3DVECTOR 型の場合は、平行移動しないと見なされる。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DERR_OUTOFVIDEOMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

D3DXMatrixAffineTransformation 関数は、次の式を使ってアフィン変換行列を計算する : Ms * Mrc-1 * Mr * Mrc * Mt。ここで、Ms はスケーリング行列、Mrc は回転行列の中心、Mr は回転行列、そして Mt は平行移動行列である。


D3DXMatrixfDeterminant

行列の行列式を返す。

D3DXMatrixfDeterminant( _
    M As D3DMATRIX) As Single

パラメータ

M
処理の基になる D3DMATRIX 型。

戻り値

行列の値、つまり行列式を返す。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DERR_OUTOFVIDEOMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。


D3DXMatrixIdentity

単位行列を作成する。

D3DXMatrixIdentity( _
    MOut As D3DMATRIX)

パラメータ

MOut
演算結果である単位行列が格納される D3DMATRIX 型。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DERR_OUTOFVIDEOMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

単位行列は、[1,1][2,2][3,3][4,4] の係数が 1 で、それ以外の係数はすべて 0 の行列である。単位行列は、頂点に適用しても頂点が変更されないという点で特殊なものである。単位行列は、頂点の値を変更して回転、平行移動、および 4 × 4 行列で表現できるほかのトランスフォームを作成する行列の起点として使用される。

参照

D3DXMatrixIsIdentity


D3DXMatrixInverse

行列の逆行列を計算する。

D3DXMatrixInverse( _
    MOut As D3DMATRIX, _
    Determinant As Single, _
    M As D3DMATRIX)

パラメータ

MOut
演算結果である行列の逆行列が格納される D3DMATRIX 型。
Determinant
関数から戻った後、行列 M の行列式である Single 値が設定されている。
M
処理の基になる D3DMATRIX 型。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DERR_OUTOFVIDEOMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

逆行列の計算が失敗した場合は、D3DXMatrixInverse 関数から空の D3DMATRIX 型が返される。Determinant パラメータが 0 でない場合は、M の行列式が返る。


D3DXMatrixIsIdentity

行列が単位行列かどうかを判定する。

D3DXMatrixIsIdentity( _
    M As D3DMATRIX) As Long

パラメータ

M
単位行列かどうかを判定する D3DMATRIX 型。

戻り値

指定する行列が単位行列の場合は、0 以外の値 (TRUE) を返す。単位行列でない場合は、0 (FALSE) を返す。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DERR_OUTOFVIDEOMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

参照

D3DXMatrixIdentity


D3DXMatrixLookAtRH

右手座標系ビュー行列 (right-handed, look-at matrix) を作成する。

D3DXMatrixLookAtRH( _
    MOut As D3DMATRIX, _
    VEye As D3DVECTOR, _
    VAt As D3DVECTOR, _
    VUp As D3DVECTOR)

パラメータ

MOut
演算結果である右手座標系ビュー行列が格納される D3DMATRIX 型。
VEye
視点を定義する D3DVECTOR 型。この値は平行移動で使用される。
VAt
カメラの注視対象を定義する D3DVECTOR 型。
VUp
カレント ワールドの上方、一般には [0, 1, 0] を定義する D3DVECTOR 型。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DERR_OUTOFVIDEOMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

参照

D3DXMatrixLookAtLH


D3DXMatrixLookAtLH

左手座標系ビュー行列 (left-handed, look-at matrix) を作成する。

D3DXMatrixLookAtLH( _
    MOut As D3DMATRIX, _
    VEye As D3DVECTOR, _
    VAt As D3DVECTOR, _
    VUp As D3DVECTOR)

パラメータ

MOut
演算結果である左手座標系ビュー行列が格納される D3DMATRIX 型。
VEye
視点を定義する D3DVECTOR 型。この値は平行移動で使用される。
VAt
カメラの注視対象を定義する D3DVECTOR 型。
VUp
カレント ワールドの上方、一般には [0, 1, 0] を定義する D3DVECTOR 型。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DERR_OUTOFVIDEOMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

参照

D3DXMatrixLookAtRH


D3DXMatrixMultiply

2 つの行列の積を計算する。

D3DXMatrixMultiply( _
    MOut As D3DMATRIX, _
    M1 As D3DMATRIX, _
    M2 As D3DMATRIX)

パラメータ

MOut
演算結果である 2 つの行列の積が格納される D3DMATRIX 型。
M1
処理の基になる D3DMATRIX 型。
M2
処理の基になる D3DMATRIX 型。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DERR_OUTOFVIDEOMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

結果は、トランスフォーム M2 の後のトランスフォーム M1 を表している (Out = M1 * M2)。

参照

D3DXQuaternionMultiply


D3DXMatrixOrthoRH

右手座標系正射影行列を作成する。

D3DXMatrixOrthoRH( _
    MOut As D3DMATRIX, _
    w As Single, _
    h As Single, _
    zn As Single, _
    zf As Single)

パラメータ

MOut
演算結果である右手座標系正射影行列が格納される D3DMATRIX 型。
w
ビュー ボリュームの幅。
h
ビュー ボリュームの高さ。
zn
ビュー ボリュームの最小 z 値。
zf
ビュー ボリュームの最大 z 値。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DERR_OUTOFVIDEOMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

正射影行列は、1 つの反転行列である。行列の反転は、行列の転置に等しい。

D3DXMatrixOrthoRH 関数のパラメータはすべて、カメラ空間の距離である。このパラメータは、ビュー ボリュームのディメンジョンを記述する。

参照

D3DXMatrixOrthoLH、D3DXMatrixOrthoOffCenterRH、D3DXMatrixOrthoOffCenterLH


D3DXMatrixOrthoLH

左手座標系正射影行列を作成する。

D3DXMatrixOrthoLH( _
    MOut As D3DMATRIX, _
    w As Single, _
    h As Single, _
    zn As Single, _
    zf As Single)

パラメータ

MOut
演算結果である左手座標系正射影行列が格納される D3DMATRIX 型。
w
ビュー ボリュームの幅。
h
ビュー ボリュームの高さ。
zn
ビュー ボリュームの最小 z 値。
zf
ビュー ボリュームの最大 z 値。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DERR_OUTOFVIDEOMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

正射影行列は、1 つの反転行列である。行列の反転は、行列の転置に等しい。

D3DXMatrixOrthoLH 関数のパラメータはすべて、カメラ空間の距離である。このパラメータは、ビュー ボリュームのディメンジョンを記述する。

参照

D3DXMatrixOrthoRH、D3DXMatrixOrthoOffCenterRH、D3DXMatrixOrthoOffCenterLH


D3DXMatrixOrthoOffCenterRH

カスタマイズされた右手座標系正射影行列を作成する。

D3DXMatrixOrthoOffCenterRH( _
    MOut As D3DMATRIX, _
    l As Single, _
    r As Single, _
    b As Single, _
    t As Single, _
    zn As Single, _
    zf As Single)

パラメータ

MOut
演算結果であるカスタマイズされた右手座標系正射影行列が格納される D3DMATRIX 型。
l
ビュー ボリュームの最小 x 値。
r
ビュー ボリュームの最大 x 値。
b
ビュー ボリュームの最大 y 値。
t
ビュー ボリュームの最小 y 値。
zn
ビュー ボリュームの最小 z 値。
zf
ビュー ボリュームの最大 z 値。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DERR_OUTOFVIDEOMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

正射影行列は、1 つの反転行列である。行列の反転は、行列の転置に等しい。

D3DXMatrixOrthoRH 関数は D3DXMatrixOrthoOffCenterRH 関数の特殊なケースである。D3DXMatrixOrthoOffCenterRH を使って同じ射影を作成するには、次の値を使用する。l = -w/2、r = w/2、b = -h/2、および t = h/2。

D3DXMatrixOrthoOffCenterRH 関数のパラメータはすべて、カメラ空間の距離である。このパラメータは、ビュー ボリュームのディメンジョンを記述する。

参照

D3DXMatrixOrthoRH、D3DXMatrixOrthoLH、D3DXMatrixOrthoOffCenterLH


D3DXMatrixOrthoOffCenterLH

カスタマイズされた左手座標系正射影行列を作成する。

D3DXMatrixOrthoOffCenterLH( _
    MOut As D3DMATRIX, _
    l As Single, _
    r As Single, _
    b As Single, _
    t As Single, _
    zn As Single, _
    zf As Single)

パラメータ

MOut
演算結果であるカスタマイズされた左手座標系正射影行列が格納される D3DMATRIX 型。
l
ビュー ボリュームの最小 x 値。
r
ビュー ボリュームの最大 x 値。
b
ビュー ボリュームの最大 y 値。
t
ビュー ボリュームの最小 y 値。
zn
ビュー ボリュームの最小 z 値。
zf
ビュー ボリュームの最大 z 値。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DERR_OUTOFVIDEOMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

正射影行列は、1 つの反転行列である。行列の反転は、行列の転置に等しい。

D3DXMatrixOrthoLH 関数は D3DXMatrixOrthoOffCenterLH 関数の特殊なケースである。D3DXMatrixOrthoOffCenterLH を使って同じ射影を作成するには、次の値を使用する。l = -w/2、r = w/2、b = -h/2、および t = h/2。

D3DXMatrixOrthoOffCenterLH 関数のパラメータはすべて、カメラ空間の距離である。このパラメータは、ビュー ボリュームのディメンジョンを記述する。

参照

D3DXMatrixOrthoRH、D3DXMatrixOrthoLH、D3DXMatrixOrthoOffCenterRH


D3DXMatrixPerspectiveRH

右手座標系パースペクティブ射影行列を作成する。

D3DXMatrixPerspectiveRH( _
    MOut As D3DMATRIX, _
    w As Single, _
    h As Single, _
    zn As Single, _
    zf As Single)

パラメータ

MOut
演算結果である右手座標系パースペクティブ射影行列が格納される D3DMATRIX 型。
w
近いビュー平面のビュー ボリュームの幅。
h
近いビュー平面のビュー ボリュームの高さ。
zn
近いビュー平面の Z 値。
zf
遠いビュー平面の Z 値。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DERR_OUTOFVIDEOMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

D3DXMatrixPerspectiveRH 関数のパラメータはすべて、カメラ空間の距離である。このパラメータは、ビュー ボリュームのディメンジョンを記述する。

参照

D3DXMatrixPerspectiveLH、D3DXMatrixPerspectiveFovRH、D3DXMatrixPerspectiveFovLH、D3DXMatrixPerspectiveOffCenterRH、D3DXMatrixPerspectiveOffCenterLH


D3DXMatrixPerspectiveFovLH

視野 (FOV) に基づいて左手座標系パースペクティブ射影行列を作成する。

D3DXMatrixPerspectiveFovLH( _
    MOut As D3DMATRIX, _
    fovy As Single, _
    aspect As Single, _
    zn As Single, _
    zf As Single)

パラメータ

MOut
演算結果である左手座標系パースペクティブ射影行列が格納される D3DMATRIX 型。
fovy
視野 (ラジアン単位)。
aspect
アスペクト比。
zn
近いビュー平面の Z 値。
zf
遠いビュー平面の Z 値。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DERR_OUTOFVIDEOMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

参照

D3DXMatrixPerspectiveRH、D3DXMatrixPerspectiveLH、D3DXMatrixPerspectiveFovRH、D3DXMatrixPerspectiveOffCenterRH、D3DXMatrixPerspectiveOffCenterLH


D3DXMatrixPerspectiveFovRH

視野 (FOV) に基づいて右手座標系パースペクティブ射影行列を作成する。

D3DXMatrixPerspectiveFovRH( _
    MOut As D3DMATRIX, _
    fovy As Single, _
    aspect As Single, _
    zn As Single, _
    zf As Single)

パラメータ

MOut
演算結果である右手座標系パースペクティブ射影行列が格納される D3DMATRIX 型。
fovy
視野 (ラジアン単位)。
aspect
アスペクト比。
zn
近いビュー平面の Z 値。
zf
遠いビュー平面の Z 値。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DERR_OUTOFVIDEOMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

参照

D3DXMatrixPerspectiveRH、D3DXMatrixPerspectiveLH、D3DXMatrixPerspectiveFovLH、D3DXMatrixPerspectiveOffCenterRH、D3DXMatrixPerspectiveOffCenterLH


D3DXMatrixPerspectiveLH

左手座標系パースペクティブ射影行列を作成する。

D3DXMatrixPerspectiveLH( _
    MOut As D3DMATRIX, _
    w As Single, _
    h As Single, _
    zn As Single, _
    zf As Single)

パラメータ

MOut
演算結果である左手座標系パースペクティブ射影行列が格納される D3DMATRIX 型。
w
近いビュー平面のビュー ボリュームの幅。
h
近いビュー平面のビュー ボリュームの高さ。
zn
近いビュー平面の Z 値。
zf
遠いビュー平面の Z 値。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DERR_OUTOFVIDEOMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

D3DXMatrixPerspectiveLH 関数のパラメータはすべて、カメラ空間の距離である。このパラメータは、ビュー ボリュームのディメンジョンを記述する。

参照

D3DXMatrixPerspectiveRH、D3DXMatrixPerspectiveFovRH、D3DXMatrixPerspectiveFovLH、D3DXMatrixPerspectiveOffCenterRH、D3DXMatrixPerspectiveOffCenterLH


D3DXMatrixPerspectiveOffCenterRH

カスタマイズされた右手座標系パースペクティブ射影行列を作成する。

D3DXMatrixPerspectiveOffCenterRH( _
    MOut As D3DMATRIX, _
    l As Single, _
    r As Single, _
    b As Single, _
    t As Single, _
    zn As Single, _
    zf As Single)

パラメータ

pOut
[in, out] 操作結果の D3DMATRIX 構造体へのポインタ。
l
[in] ビュー ボリュームの最小 X 値。
r
[in] ビュー ボリュームの最大 X 値。
t
[in] ビュー ボリュームの最小 Y 値。
b
[in] ビュー ボリュームの最大 Y 値。
zn
[in] ビュー ボリュームの最小 Z 値。
zf
[in] ビュー ボリュームの最大 Z 値。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DERR_OUTOFVIDEOMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

D3DXMatrixPerspectiveOffCenterRH 関数のパラメータはすべて、カメラ空間の距離である。このパラメータは、ビュー ボリュームのディメンジョンを記述する。

参照

D3DXMatrixPerspectiveRH、D3DXMatrixPerspectiveLH、D3DXMatrixPerspectiveFovRH、D3DXMatrixPerspectiveFovLH、D3DXMatrixPerspectiveOffCenterLH


D3DXMatrixPerspectiveOffCenterLH

カスタマイズされた左手座標系パースペクティブ射影行列を作成する。

D3DXMatrixPerspectiveOffCenterLH( _
    MOut As D3DMATRIX, _
    l As Single, _
    r As Single, _
    b As Single, _
    t As Single, _
    zn As Single, _
    zf As Single)

パラメータ

pOut
[in, out] 操作結果の D3DMATRIX 構造体へのポインタ。
l
[in] ビュー ボリュームの最小 X 値。
r
[in] ビュー ボリュームの最大 X 値。
t
[in] ビュー ボリュームの最小 Y 値。
b
[in] ビュー ボリュームの最大 Y 値。
zn
[in] ビュー ボリュームの最小 Z 値。
zf
[in] ビュー ボリュームの最大 Z 値。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DERR_OUTOFVIDEOMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

D3DXMatrixPerspectiveOffCenterLH 関数のパラメータはすべて、カメラ空間の距離である。このパラメータは、ビュー ボリュームのディメンジョンを記述する。

参照

D3DXMatrixPerspectiveRH、D3DXMatrixPerspectiveLH、D3DXMatrixPerspectiveFovRH、D3DXMatrixPerspectiveFovLH、D3DXMatrixPerspectiveOffCenterRH


D3DXMatrixReflect

平面に対して座標系を反転する行列を作成する。

D3DXMatrixReflect( _
    MOut As D3DMATRIX, _
    Plane As D3DPLANE)

パラメータ

MOut
演算結果である、基になる平面に対して座標系を反転する行列が格納される D3DMATRIX 型。
Plane
処理の基になる D3DPLANE 型。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DERR_OUTOFVIDEOMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。


D3DXMatrixRotationAxis

任意の軸を回転軸にして回転する行列を作成する。

D3DXMatrixRotationAxis( _
    MOut As D3DMATRIX, _
    VAxis As D3DVECTOR, _
    angle As Single)

パラメータ

MOut
演算結果である、指定された軸を中心にして回転する行列が格納される D3DMATRIX 型。
VAxis
軸角度を識別する D3DVECTOR 型。
angle
回転の角度 (ラジアン単位)。角度は、回転軸を中心にして原点方向を向いた時計回りで測定したものである。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DERR_OUTOFVIDEOMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

参照

D3DXMatrixRotationQuaternion、D3DXMatrixRotationX、D3DXMatrixRotationY、D3DXMatrixRotationYawPitchRoll、D3DXMatrixRotationZ


D3DXMatrixRotationQuaternion

クオータニオンから行列を作成する。

D3DXMatrixRotationQuaternion( _
    MOut As D3DMATRIX, _
    Q As D3DQUATERNION)

パラメータ

MOut
演算結果である、基になるクオータニオンから作成された行列が格納される D3DMATRIX 型。
Q
処理の基になる D3DQUATERNION 型。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DERR_OUTOFVIDEOMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

参照

D3DXMatrixRotationAxis、D3DXMatrixRotationX、D3DXMatrixRotationY、D3DXMatrixRotationYawPitchRoll、D3DXMatrixRotationZ


D3DXMatrixRotationX

x 軸を回転軸にして回転する行列を作成する。

D3DXMatrixRotationX( _
    MOut As D3DMATRIX, _
    angle As Single)

パラメータ

MOut
演算結果である、x 軸を中心にして回転する行列が格納される D3DMATRIX 型。
angle
回転の角度 (ラジアン単位)。角度は、回転軸を中心にして原点方向を向いた時計回りで測定したものである。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DERR_OUTOFVIDEOMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

参照

D3DXMatrixRotationAxis、D3DXMatrixRotationQuaternion、D3DXMatrixRotationY、D3DXMatrixRotationYawPitchRoll、D3DXMatrixRotationZ


D3DXMatrixRotationY

y 軸を回転軸にして回転する行列を作成する。

D3DXMatrixRotationY( _
    MOut As D3DMATRIX, _
    angle As Single)

パラメータ

MOut
演算結果である、y 軸を中心にして回転する行列が格納される D3DMATRIX 型。
angle
回転の角度 (ラジアン単位)。角度は、回転軸を中心にして原点方向を向いた時計回りで測定したものである。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DERR_OUTOFVIDEOMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

参照

D3DXMatrixRotationAxis、D3DXMatrixRotationQuaternion、D3DXMatrixRotationX、D3DXMatrixRotationYawPitchRoll、D3DXMatrixRotationZ


D3DXMatrixRotationYawPitchRoll

指定されたヨー、ピッチ、およびロールで行列を作成する。

D3DXMatrixRotationYawPitchRoll( _
    MOut As D3DMATRIX, _
    yaw As Single, _
    pitch As Single, _
    roll As Single)

パラメータ

MOut
演算結果である、指定されたヨー、ピッチ、およびロールの行列が格納される D3DMATRIX 型。
yaw
y 軸を中心とするヨー (ラジアン単位)。
pitch
x 軸を中心とするピッチ (ラジアン単位)。
roll
z 軸を中心とするロール (ラジアン単位)。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DERR_OUTOFVIDEOMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

参照

D3DXMatrixRotationAxis、D3DXMatrixRotationQuaternion、D3DXMatrixRotationX、D3DXMatrixRotationY、D3DXMatrixRotationZ


D3DXMatrixRotationZ

z 軸を回転軸にして回転する行列を作成する。

D3DXMatrixRotationZ( _
    MOut As D3DMATRIX, _
    angle As Single)

パラメータ

MOut
演算結果である、z 軸を中心にして回転する行列が格納される D3DMATRIX 型。
angle
回転の角度 (ラジアン単位)。角度は、回転軸を中心にして原点方向を向いた時計回りで測定したものである。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DERR_OUTOFVIDEOMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

参照

D3DXMatrixRotationAxis、D3DXMatrixRotationQuaternion、D3DXMatrixRotationX、D3DXMatrixRotationY、D3DXMatrixRotationYawPitchRoll


D3DXMatrixScaling

x 軸、y 軸、z 軸に沿ってスケーリングする行列を作成する。

D3DXMatrixScaling( _
    MOut As D3DMATRIX, _
    x As Single, _
    y As Single, _
    z As Single)

パラメータ

MOut
演算結果であるスケーリングされた行列が格納される D3DMATRIX 型。
x
x 軸に沿って適用されるスケーリング係数。
y
y 軸に沿って適用されるスケーリング係数。
z
z 軸に沿って適用されるスケーリング係数。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DERR_OUTOFVIDEOMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。


D3DXMatrixShadow

ライトによる影をキャストするように、ジオメトリを指定した平面に射影する行列を作成する。「注意」を参照すること。

D3DXMatrixShadow( _
    MOut As D3DMATRIX, _
    VLight As D3DVECTOR4, _
    Plane As D3DPLANE)

パラメータ

MOut
演算結果である、ジオメトリを平面に射影する行列が格納される D3DMATRIX 型。「注意」を参照すること。
VLight
ライトの位置を示す D3DVECTOR4 型。
Plane
処理の基になる D3DPLANE 型。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DERR_OUTOFVIDEOMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

D3DXMatrixShadow 関数は、ジオメトリを平面に射影する行列を作成する。Vlight.w が 0 の場合、原点から Vlight へのレイがディレクショナル ライトを表す。Vlight.w が 1 の場合は、Vlight はポイント ライトを表す。


D3DXMatrixTransformation

トランスフォーム行列を作成する。

D3DXMatrixTransformation( _
    MOut As D3DMATRIX, _
    VScaleCenter As D3DVECTOR, _
    QScaleRotation As D3DQUATERNION, _
    VScale As D3DVECTOR, _
    VRotationCenter As D3DVECTOR, _
    QRotation As D3DQUATERNION, _
    VTranslation As D3DVECTOR)

パラメータ

MOut
演算結果であるトランスフォーム行列が格納される D3DMATRIX 型。
VScaleCenter
スケーリングの中心点を識別する D3DVECTOR 型。この引数が空の D3DVECTOR 型の場合は、スケールしないと見なされる。
QScaleRotation
スケーリングの回転を指定する D3DQUATERNION 型。この引数が空の D3DQUATERNION 型の場合は、スケールしないと見なされる。
VScale
スケーリング ベクトルを示す D3DVECTOR 型。この引数が空の D3DVECTOR 型の場合は、スケールしないと見なされる。
VRotationCenter
回転の中心を識別する D3DVECTOR 型。この引数が空の D3DVECTOR 型の場合は、回転しないと見なされる。
QRotation
回転を指定する D3DQUATERNION 型。この引数が空の D3DQUATERNION 型の場合は、回転しないと見なされる。
VTranslation
平行移動を表す D3DVECTOR 型。この引数が空の D3DVECTOR 型の場合は、平行移動しないと見なされる。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DERR_OUTOFVIDEOMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

D3DXMatrixTransformation 関数は、次の式を使ってトランスフォーム行列を計算する: Msc-1 * Msr-1 * Ms * Msr * Msc * Mrc-1 * Mr * Mrc * Mt。ここで、Msc は中心のスケーリング行列、Msr はスケーリング回転行列、Ms はスケーリング行列、Mrc は回転行列の中心、Mr は回転行列、Mt は平行移動行列である。

参照

D3DXMatrixAffineTransformation


D3DXMatrixTranslation

指定されたオフセットを使って行列を作成する。

D3DXMatrixTranslation( _
    MOut As D3DMATRIX, _
    x As Single, _
    y As Single, _
    z As Single)

パラメータ

MOut
演算結果である平行移動された行列が格納される D3DMATRIX 型。
x
x 座標のオフセット。
y
y 座標のオフセット。
z
z 座標のオフセット。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DERR_OUTOFVIDEOMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。


D3DXMatrixTranspose

指定された行列の転置行列を返す。

D3DXMatrixTranspose( _
    MOut As D3DMATRIX, _
    M As D3DMATRIX)

パラメータ

MOut
演算結果である、指定する行列の転置行列が格納される D3DMATRIX 型。
M
処理の基になる D3DMATRIX 型。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DERR_OUTOFVIDEOMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。


D3DXPlaneDot

平面と 4D ベクトルの内積を計算する。

D3DXPlaneDot( _
    P1 As D3DPLANE, _
    P2 As D3DPLANE) As Single

パラメータ

P1
処理の基になる D3DPLANE 型。
P2
処理の基になる D3DPLANE 型。

戻り値

平面と 4D ベクトルの内積。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DERR_OUTOFVIDEOMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

平面 (a, b, c, d) と 4D ベクトル (x, y, z, w) を指定した場合、この関数の戻り値は a*x + b*y + c*z + d*w になる。関数 D3DXPlaneDot は、平面と同次座標の関係を判断するときに役に立つ。たとえば、この関数を使うと、特定の座標が特定の平面上にあるかどうか、または特定の座標が特定の平面のどちら側にあるかを判断できる。

参照

D3DXPlaneDotCoord、D3DXPlaneDotNormal


D3DXPlaneDotCoord

平面と 3D ベクトルの内積を計算する。ベクトルの w パラメータは、1 であると見なされる。

D3DXPlaneDotCoord( _
    P1 As D3DPLANE, _
    V As D3DVECTOR) As Single

パラメータ

P1
処理の基になる D3DPLANE 型。
V
処理の基になる D3DVECTOR 型。

戻り値

平面と 3D ベクトルの内積。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DERR_OUTOFVIDEOMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

平面 (a, b, c, d) と 3D ベクトル (x, y, z) を指定した場合、この関数の戻り値は a*x + b*y + c*z + d*1 になる。関数 D3DXPlaneDotCoord は、平面と 3D 空間の座標の関係を判断するときに役に立つ。

参照

D3DXPlaneDot、D3DXPlaneDotNormal


D3DXPlaneDotNormal

平面と 3D ベクトルの内積を計算する。ベクトルの w パラメータは、0 であると見なされる。

D3DXPlaneDotNormal( _
    P1 As D3DPLANE, _
    V As D3DVECTOR) As Single

パラメータ

P1
処理の基になる D3DPLANE 型。
V
処理の基になる D3DVECTOR 型。

戻り値

平面と 3D ベクトルの内積。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DERR_OUTOFVIDEOMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

平面 (a, b, c, d) と 3D ベクトル (x, y, z) を指定した場合、この関数の戻り値は *x + b*y + c*z + d*0 になる。関数 D3DXPlaneDotNormal は、平面の法線と別の法線の間の角度を判断するときに役に立つ。

参照

D3DXPlaneDot、D3DXPlaneDotCoord


D3DXPlaneFromPointNormal

ポイントと法線から平面を作成する。

D3DXPlaneFromPointNormal( _
    POut As D3DPLANE, _
    VPoint As D3DVECTOR, _
    vNormal As D3DVECTOR)

パラメータ

POut
演算結果である、ポイントと法線から作成された平面が格納される D3DPLANE 型。
VPoint
平面を作成するときに使用するポイントを定義する D3DVECTOR 型。
vNormal
平面を作成するときに使用する法線を定義する D3DVECTOR 型。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DERR_OUTOFVIDEOMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

参照

D3DXPlaneFromPoints


D3DXPlaneFromPoints

3 つのポイントから平面を作成する。

D3DXPlaneFromPoints( _
    POut As D3DPLANE, _
    V1 As D3DVECTOR, _
    V2 As D3DVECTOR, _
    V3 As D3DVECTOR)

パラメータ

POut
演算結果である、指定したポイントから作成された平面が格納される D3DPLANE 型。
V1
平面の作成に使用するポイントの 1 つを定義する D3DVECTOR 型。
V2
平面の作成に使用するポイントの 1 つを定義する D3DVECTOR 型。
V3
平面の作成に使用するポイントの 1 つを定義する D3DVECTOR 型。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DERR_OUTOFVIDEOMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

参照

D3DXPlaneFromPointNormal


D3DXPlaneIntersectLine

平面と直線の交点を見つける。

D3DXPlaneIntersectLine( _
    POut As D3DPLANE, _
    P As D3DPLANE, _
    V1 As D3DVECTOR, _
    V2 As D3DVECTOR)

パラメータ

POut
演算結果である、指定された平面と直線の交点が格納される D3DPLANE 型。
P
処理の基になる D3DPLANE 型。
V1
処理の基になる D3DVECTOR 型。線の基点を定義する。
V2
処理の基になる D3DVECTOR 型。線の終点を定義する。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DERR_OUTOFVIDEOMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

直線が平面に対して平行の場合は、空の D3DPLANE 型が返る。


D3DXPlaneNormalize

正規化した平面を返す。

D3DXPlaneNormalize( _
    POut As D3DPLANE, _
    P As D3DPLANE)

パラメータ

POut
演算結果である平面の法線が格納される D3DPLANE 型。
P
処理の基になる D3DPLANE 型。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DERR_OUTOFVIDEOMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

D3DXPlaneNormalize は、|a,b,c| == 1 となるように平面を正規化する。


D3DXPlaneTransform

指定された行列で平面をトランスフォームする。

D3DXPlaneTransform( _
    POut As D3DPLANE, _
    P As D3DPLANE, _
    M As D3DMATRIX)

パラメータ

POut
演算結果であるトランスフォームされた平面が格納される D3DPLANE 型。
P
処理の基になる D3DPLANE 型。
M
処理の基になる D3DMATRIX 型。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DERR_OUTOFVIDEOMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

行列 M は、アフィン変換でなければならない。


D3DXQuaternionBaryCentric

重心座標のクオータニオンを返す。

D3DXQuaternionBaryCentric( _
    QOut As D3DQUATERNION, _
    Q1 As D3DQUATERNION, _
    Q2 As D3DQUATERNION, _
    Q3 As D3DQUATERNION, _
    f As Single, _
    g As Single)

パラメータ

QOut
演算結果である重心座標のクオータニオンが格納される D3DQUATERNION 型。
Q1
処理の基になる D3DQUATERNION 型。
Q2
処理の基になる D3DQUATERNION 型。
Q3
処理の基になる D3DQUATERNION 型。
f
加重係数。「注意」を参照すること。
g
加重係数。「注意」を参照すること。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DERR_OUTOFVIDEOMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

重心座標を計算するために、D3DXQuaternionBaryCentric 関数は、次の球状線形補間演算を実装する。Slerp(Slerp(Q1, Q2, f+g), Slerp(Q1, Q3, f+g), g/(f+g))


D3DXQuaternionConjugate

指定されたクオータニオンの共役を返す。

D3DXQuaternionConjugate( _
    QOut As D3DQUATERNION, _
    Q As D3DQUATERNION)

パラメータ

QOut
演算結果であるクオータニオンの共役が格納される D3DQUATERNION 型。
Q
処理の基になる D3DQUATERNION 型。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DERR_OUTOFVIDEOMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

クオータニオン (x, y, z, w) を指定すると、D3DXQuaternionConjugate 関数からはクオータニオン (-x, -y, -z, w) が返る。

参照

D3DXQuaternionInverse


D3DXQuaternionDot

指定されたクオータニオンの共役を返す。

D3DXQuaternionDot( _
    Q1 As D3DQUATERNION, _
    Q2 As D3DQUATERNION)

パラメータ

Q1
処理の基になる D3DQUATERNION 型。
Q2
処理の基になる D3DQUATERNION 型。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DERR_OUTOFVIDEOMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。


D3DXQuaternionExp

指数関数を計算する。

D3DXQuaternionExp( _
    QOut As D3DQUATERNION, _
    Q As D3DQUATERNION)

パラメータ

QOut
演算結果である指数関数が格納される D3DQUATERNION 型。
Q
処理の基になる D3DQUATERNION 型。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DERR_OUTOFVIDEOMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

D3DXQuaternionExp 関数は、w == 0 の単一クオータニオンでのみ機能する。

この関数は、次の方法で実装される。

q = (0, theta * v)
Exp(q) = (Cos(theta), Sin(theta) * v)

D3DXQuaternionExp 関数と D3DXQuaternionLn 関数は、D3DXQuaternionSquad 関数を使用するときに役に立つ。クオータニオン キーのセット (q0, q1, q2, ..., qn) を指定すると、次の例に示すように、内部四角形のポイント (a1, a2, a3, ..., an-1) が計算されて、隣接するセグメント間で接線が連続することを保証できる。

        a1    a2    a3
  q0    q1    q2    q3    q4

a[i] = q[i] * Exp( -(ln(inv(q[i])*q[i+1]) + ln(inv(q[i])*q[i-1])) / 4 )

(a1, a2, a3, ...) が一度計算されると、その結果を使用してカーブに沿って補間できる。

qt = Squad(t, q[i], a[i], a[i+1], q[i+1])

参照

D3DXQuaternionLn、D3DXQuaternionSquad


D3DXQuaternionIdentity

正規化されたクオータニオンを返す。

D3DXQuaternionIdentity( _
    QOut As D3DQUATERNION)

パラメータ

QOut
演算結果である正規化されたクオータニオンが格納される D3DQUATERNION 型。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DERR_OUTOFVIDEOMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

クオータニオン (x, y, z, w) を指定すると、D3DXQuaternionIdentity 関数からはクオータニオン (0, 0, 0, 1) が返る。

参照

D3DXQuaternionIsIdentity


D3DXQuaternionInverse

クオータニオンを共役して再正規化する。

D3DXQuaternionInverse( _
    QOut As D3DQUATERNION, _
    Q As D3DQUATERNION)

パラメータ

QOut
演算結果である、クオータニオンの逆クオータニオンが格納される D3DQUATERNION 型。
Q
処理の基になる D3DQUATERNION 型。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DERR_OUTOFVIDEOMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

参照

D3DXQuaternionConjugate、D3DXQuaternionNormalize


D3DXQuaternionIsIdentity

クオータニオンが正規化されたクオータニオンかどうかを判定する。

D3DXQuaternionIsIdentity( _
    Q As D3DQUATERNION) As Long

パラメータ

Q
正規化されたクオータニオンかどうかを判定する D3DQUATERNION 型。

戻り値

指定したクオータニオンが正規化されたクオータニオンの場合は、0 以外の値 (TRUE) を返す。正規化されたクオータニオンでない場合は、0 (FALSE) を返す。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DERR_OUTOFVIDEOMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

参照

D3DXQuaternionIdentity


D3DXQuaternionLength

指定されたクオータニオンの長さを返す。

D3DXQuaternionLength( _
    Q As D3DQUATERNION) As Single

パラメータ

Q
処理の基になる D3DQUATERNION 型。

戻り値

クオータニオンの長さ。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DERR_OUTOFVIDEOMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

参照

D3DXQuaternionLengthSq


D3DXQuaternionLengthSq

指定されたクオータニオンの長さの 2 乗を返す。

D3DXQuaternionLengthSq( _
    Q As D3DQUATERNION) As Single

パラメータ

Q
処理の基になる D3DQUATERNION 型。

戻り値

クオータニオンの長さの 2 乗。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DERR_OUTOFVIDEOMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

参照

D3DXQuaternionLength


D3DXQuaternionLn

自然対数を計算する。

D3DXQuaternionLn( _
    QOut As D3DQUATERNION, _
    Q As D3DQUATERNION)

パラメータ

QOut
演算結果である自然対数が格納される D3DQUATERNION 型。
Q
処理の基になる D3DQUATERNION 型。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DERR_OUTOFVIDEOMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

D3DXQuaternionLn 関数は、正規化されたクオータニオンに対してのみ機能する。

この関数は、次の方法で実装される。

q = (Cos(theta), Sin(theta) * v)
|v| = 1
ln(q) = (0, theta * v)

D3DXQuaternionExp 関数と D3DXQuaternionLn 関数は、D3DXQuaternionSquad 関数を使用するときに役に立つ。クオータニオン キーのセット (q0, q1, q2, ..., qn) を指定すると、内部四角形のポイント (a1, a2, a3, ..., an-1) が計算されて、隣接するセグメント間で接線が連続することを保証できる。

        a1    a2    a3
  q0    q1    q2    q3    q4

a[i] = q[i] * Exp( -(ln(inv(q[i])*q[i+1]) + ln(inv(q[i])*q[i-1])) / 4 )

(a1, a2, a3, ...) が一度計算されると、その結果を使用してカーブに沿って補間できる。

qt = Squad(t, q[i], a[i], a[i+1], q[i+1])

参照

D3DXQuaternionExp、D3DXQuaternionSquad


D3DXQuaternionMultiply

2 つのクオータニオンの積を計算する。

D3DXQuaternionMultiply( _
    QOut As D3DQUATERNION, _
    Q1 As D3DQUATERNION, _
    Q2 As D3DQUATERNION)

パラメータ

QOut
演算結果である 2 つのクオータニオンの積が格納される D3DQUATERNION 型。
Q1
処理の基になる D3DQUATERNION 型。
Q2
処理の基になる D3DQUATERNION 型。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DERR_OUTOFVIDEOMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

結果は、回転 Q2 に続いて回転 Q1 を実行する処理を表している (Out = Q2 * Q1)。出力は実際には Q2*Q1 である (Q1*Q2 ではない)。正規化されたクオータニオンは回転行列を別の方法で表したものと見なすことができるため、このような計算順序にすることで、D3DXQuaternionMultiply と D3DXMatrixMultiply のセマンティクスの同一性が保たれる。

D3DXQuaternionMultiply 関数と D3DXMatrixMultiply 関数の両方において、トランスフォームは同じ順序で連結される。たとえば、次の例では、mX および mY が qX および qY と同じ回転を表しているとすると、m と q は同じ回転を表すことになる。

D3DXMatrixMultiply m, mX, mY

D3DXQuaternionMultiply q, qX, qY

クオータニオンの乗算は可換ではない。

参照

D3DXMatrixMultiply


D3DXQuaternionNormalize

正規化されたクオータニオンを返す。

D3DXQuaternionNormalize( _
    QOut As D3DQUATERNION, _
    Q As D3DQUATERNION)

パラメータ

QOut
演算結果である正規化されたクオータニオンが格納される D3DQUATERNION 型。
Q
処理の基になる D3DQUATERNION 型。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DERR_OUTOFVIDEOMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

参照

D3DXQuaternionInverse


D3DXQuaternionRotationAxis

任意の軸を回転軸としてクオータニオンを回転させる。

D3DXQuaternionRotationAxis( _
    QOut As D3DQUATERNION, _
    VAxis As D3DVECTOR, _
    angle As Single)

パラメータ

QOut
演算結果である、指定された軸を中心として回転されたクオータニオンが格納される D3DQUATERNION 型。
VAxis
軸角度を識別する D3DVECTOR 型。
angle
回転の角度 (ラジアン単位)。角度は、回転軸を中心にして原点方向を向いた時計回りで測定したものである。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DERR_OUTOFVIDEOMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

参照

D3DXQuaternionRotationMatrix、D3DXQuaternionRotationYawPitchRoll


D3DXQuaternionRotationMatrix

回転行列からクオータニオンを作成する。

D3DXQuaternionRotationMatrix( _
    QOut As D3DQUATERNION, _
    M As D3DMATRIX)

パラメータ

QOut
演算結果である、回転行列から作成されたクオータニオンが格納される D3DQUATERNION 型。
M
処理の基になる D3DMATRIX 型。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DERR_OUTOFVIDEOMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

参照

D3DXQuaternionRotationAxis、D3DXQuaternionRotationYawPitchRoll


D3DXQuaternionRotationYawPitchRoll

指定されたヨー、ピッチ、およびロールでクオータニオンを作成する。

D3DXQuaternionRotationYawPitchRoll( _
    QOut As D3DQUATERNION, _
    yaw As Single, _
    pitch As Single, _
    roll As Single)

パラメータ

QOut
演算結果である、指定したヨー、ピッチ、およびロールのクオータニオンが格納される D3DQUATERNION 型。
yaw
y 軸を中心とするヨー (ラジアン単位)。
pitch
x 軸を中心とするピッチ (ラジアン単位)。
roll
z 軸を中心とするロール (ラジアン単位)。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DERR_OUTOFVIDEOMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

参照

D3DXQuaternionRotationAxis、D3DXQuaternionRotationMatrix


D3DXQuaternionSlerp

球状線形補間を使用して、2 つのクオータニオンの間を補間する。

D3DXQuaternionSlerp( _
    QOut As D3DQUATERNION, _
    Q1 As D3DQUATERNION, _
    Q2 As D3DQUATERNION, _
    t As Single)

パラメータ

QOut
演算結果である補間の結果が格納される D3DQUATERNION 型。
Q1
処理の基になる D3DQUATERNION 型。
Q2
処理の基になる D3DQUATERNION 型。
t
補間するクオータニオン間の間隔を示すパラメータ。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DERR_OUTOFVIDEOMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。


D3DXQuaternionSquad

球状平方補間を使用して、クオータニオンの間を補間する。

D3DXQuaternionSquad( _
    QOut As D3DQUATERNION, _
    Q1 As D3DQUATERNION, _
    Q2 As D3DQUATERNION, _
    Q3 As D3DQUATERNION, _
    Q4 As D3DQUATERNION, _
    t As Single)

パラメータ

QOut
演算結果である球状平方補間の結果が格納される D3DQUATERNION 型。
Q1
処理の基になる D3DQUATERNION 型。
Q2
処理の基になる D3DQUATERNION 型。
Q3
処理の基になる D3DQUATERNION 型。
Q4
処理の基になる D3DQUATERNION 型。
t
補間するクオータニオン間の間隔を示すパラメータ。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DERR_OUTOFVIDEOMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

この関数は、次の球状線形補間演算を使用する。Slerp(Slerp(Q1, Q4, t), Slerp(Q2, Q3, t), 2t(1-t))

参照

D3DXQuaternionExp、D3DXQuaternionLn


D3DXQuaternionToAxisAngle

クオータニオンの軸と回転角度を計算する。

D3DXQuaternionToAxisAngle( _
    Q As D3DQUATERNION, _
    VAxis As D3DVECTOR, _
    angle As Single) As Long

パラメータ

Q
処理の基になる D3DQUATERNION 型。
VAxis
この関数から返った時点で、この D3DVECTOR 型にはクオータニオンの軸を示す値が格納されている。
angle
この関数から返った時点で、この Single 値には、クオータニオンの回転角度 (ラジアン単位) を示す値が格納されている。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DERR_OUTOFVIDEOMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

この関数は、正規化されたクオータニオンが渡されることを想定している。


D3DXVec2Add

2 つの 2D ベクトルを追加する。

D3DXVec2Add( _
    VOut As D3DVECTOR2, _
    V1 As D3DVECTOR2, _
    V2 As D3DVECTOR2)

パラメータ

VOut
演算結果である 2 つのベクトルの和が格納される D3DVECTOR2 型。
V1
処理の基になる D3DVECTOR2 型。
V2
処理の基になる D3DVECTOR2 型。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DERR_OUTOFVIDEOMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

参照

D3DXVec2Subtract、D3DXVec2Scale


D3DXVec2BaryCentric

指定した 2D ベクトルを使用して、重心座標のポイントを返す。

D3DXVec2BaryCentric( _
    VOut As D3DVECTOR2, _
    V1 As D3DVECTOR2, _
    V2 As D3DVECTOR2, _
    V3 As D3DVECTOR2, _
    f As Single, _
    g As Single)

パラメータ

VOut
演算結果である重心座標のベクトルが格納される D3DVECTOR2 型。
V1
処理の基になる D3DVECTOR2 型。
V2
処理の基になる D3DVECTOR2 型。
V3
処理の基になる D3DVECTOR2 型。
f
加重係数。「注意」を参照すること。
g
加重係数。「注意」を参照すること。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DERR_OUTOFVIDEOMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

D3DXVec2BaryCentric 関数は、三角形の実際の位置とは関係なく、三角形の内部および周辺のポイントを認識する手段を提供する。この関数は、次の方程式を使用して、結果として描画されるポイントを返す: V1 + f(V2-V1) + g(V3-V1)。

平面 V1V2V3 のポイントはいずれも、重心座標 (f,g) で表すことができる。パラメータ f は、V2 の結果に対する加重を制御し、パラメータ g は、V3 の結果に対する加重を制御する。最後に、1-f-g は V1 の結果に対する加重を制御する。

次の関係に注意すること。

  • (f>=0 And g>=0 And 1-f-g>=0) の場合、ポイントは三角形 V1V2V3 の中にある。
  • (f==0 And g>=0 And 1-f-g>=0) の場合、ポイントは線 V1V3 上にある。
  • (f>=0 And g==0 And 1-f-g>=0) の場合、ポイントは線 V1V2 上にある。
  • (f>=0 And g>=0 And 1-f-g==0) の場合、ポイントは線 V2V3 上にある。

重心座標は一般座標の 1 つの形式である。このコンテキストでは、重心座標を使用して座標システムの変化を簡単に表している。デカルト座標で TRUE のものは、重心座標でも TRUE である。


D3DXVec2CatmullRom

指定された 2D ベクトルを使用して Catmull-Rom 補間を実行する。

D3DXVec2CatmullRom( _
    VOut As D3DVECTOR2, _
    V0 As D3DVECTOR2, _
    V1 As D3DVECTOR2, _
    V2 As D3DVECTOR2, _
    V3 As D3DVECTOR2, _
    s As Single)

パラメータ

VOut
演算結果が格納される D3DVECTOR2 型。
V0
D3DVECTOR2 型。位置ベクトルを示す。
V1
D3DVECTOR2 型。位置ベクトルを示す。
V2
D3DVECTOR2 型。位置ベクトルを示す。
V3
D3DVECTOR2 型。位置ベクトルを示す。
s
加重係数。「注意」を参照すること。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DERR_OUTOFVIDEOMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

D3DXVec2CatmullRom 関数は、Catmull-Rom 補間を使用して、位置 V1 (s が 0 の場合) の間と、位置 V2 (s が 1 の場合) の間の補間を行う。


D3DXVec3CatmullRom

指定された 3D ベクトルを使用して Catmull-Rom 補間を実行する。

D3DXVec3CatmullRom( _
    VOut As D3DVECTOR, _
    V0 As D3DVECTOR, _
    V1 As D3DVECTOR, _
    V2 As D3DVECTOR, _
    V3 As D3DVECTOR, _
    s As Single)

パラメータ

VOut
演算結果が格納される D3DVECTOR 型。
V0
D3DVECTOR 型。位置ベクトルを示す。
V1
D3DVECTOR 型。位置ベクトルを示す。
V2
D3DVECTOR 型。位置ベクトルを示す。
V3
D3DVECTOR 型。位置ベクトルを示す。
s
加重係数。「注意」を参照すること。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DERR_OUTOFVIDEOMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

D3DXVec3CatmullRom 関数は、Catmull-Rom 補間を使用して、位置 V1 (s が 0 の場合) の間と、位置 V2 (s が 1 の場合) の間の補間を行う。


D3DXVec2CCW

2 つの 2D ベクトルの外積を計算し、z 要素を返す。

D3DXVec2CCW( _
    V1 As D3DVECTOR2, _
    V2 As D3DVECTOR2) As Single

パラメータ

V1
処理の基になる D3DVECTOR2 型。
V2
処理の基になる D3DVECTOR2 型。

戻り値

z 要素。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DERR_OUTOFVIDEOMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

この関数は、次の公式に基づく外積から z 要素を決定する。((x1,y1,0) * (x2,y2,0)); または次の例のような式を使用する。

V1.x * V2.y - V1.y * V2.x

z 要素の値が正の場合、ベクトル V2 はベクトル V1 から反時計回りである。この情報は、背面のカリングに役立つ。

参照

D3DXVec2Dot


D3DXVec2Dot

2 つの 2D ベクトルの内積を判定する。

D3DXVec2Dot( _
    V1 As D3DVECTOR2, _
    V2 As D3DVECTOR2) As Single

パラメータ

V1
処理の基になる D3DVECTOR2 型。
V2
処理の基になる D3DVECTOR2 型。

戻り値

内積。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DERR_OUTOFVIDEOMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

参照

D3DXVec2CCW


D3DXVec2Hermite

指定された 2D ベクトルを使用してエルミートのスプライン補間を実行する。

D3DXVec2Hermite( _
    VOut As D3DVECTOR2, _
    V1 As D3DVECTOR2, _
    T1 As D3DVECTOR2, _
    V2 As D3DVECTOR2, _
    T2 As D3DVECTOR2, _
    s As Single)

パラメータ

VOut
演算結果であるエルミートのスプライン補間が格納される D3DVECTOR2 型。
V1
処理の基になる D3DVECTOR2 型。位置ベクトルを示す。
T1
処理の基になる D3DVECTOR2 型。接線ベクトルを示す。
V2
処理の基になる D3DVECTOR2 型。位置ベクトルを示す。
T2
処理の基になる D3DVECTOR2 型。接線ベクトルを示す。
s
加重係数。「注意」を参照すること。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DERR_OUTOFVIDEOMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

関数 D3DXVec2Hermite は、エルミートのスプライン補間を使用して、(positionA, tangentA) から (positionB, tangentB) までを補間する。s が 0 の場合は位置 V1 と接線 T1 の間を補間し、s が 1 の場合は位置 V2 と接線 T2 の間を補間する。

カーブはすべての制御点を通って実行されるので、エルミートのスプラインはアニメーションの制御に便利である。また、位置および接線は各セグメントの最後に明示的に指定されるので、開始位置および接線が最後のセグメントの終わり値に一致していることが確認されている限り、C2 の継続的なカーブの作成は簡単である。


D3DXVec2Length

2D ベクトルの長さを返す。

D3DXVec2Length( _
    v As D3DVECTOR2) As Single

パラメータ

v
処理の基になる D3DVECTOR2 型。

戻り値

ベクトルの長さ。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DERR_OUTOFVIDEOMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

参照

D3DXVec2LengthSq


D3DXVec2LengthSq

2D ベクトルの長さの 2 乗を返す。

D3DXVec2LengthSq( _
    v As D3DVECTOR2) As Single

パラメータ

v
処理の基になる D3DVECTOR2 型。

戻り値

ベクトルの 2 乗された長さ。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DERR_OUTOFVIDEOMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

参照

D3DXVec2Length


D3DXVec2Lerp

2 つの 2D ベクトル間の線形補間を実行する。

D3DXVec2Lerp( _
    VOut As D3DVECTOR2, _
    V1 As D3DVECTOR2, _
    V2 As D3DVECTOR2, _
    s As Single)

パラメータ

VOut
演算結果である線形補間が格納される D3DVECTOR2 型。
V1
処理の基になる D3DVECTOR2 型。
V2
処理の基になる D3DVECTOR2 型。
s
ベクトル間を線形補間するパラメータ。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DERR_OUTOFVIDEOMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。


D3DXVec2Maximize

2 つの 2D ベクトルの最大値で構成される 2D ベクトルを返す。

D3DXVec2Maximize( _
    VOut As D3DVECTOR2, _
    V1 As D3DVECTOR2, _
    V2 As D3DVECTOR2)

パラメータ

VOut
演算結果である、2 つのベクトルの最大値から成るベクトルが格納される D3DVECTOR2 型。
V1
処理の基になる D3DVECTOR2 型。
V2
処理の基になる D3DVECTOR2 型。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DERR_OUTOFVIDEOMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

参照

D3DXVec2Minimize


D3DXVec2Minimize

2 つの 2D ベクトルの最小値で構成される 2D ベクトルを返す。

D3DXVec2Minimize( _
    VOut As D3DVECTOR2, _
    V1 As D3DVECTOR2, _
    V2 As D3DVECTOR2)

パラメータ

VOut
演算結果である、2 つのベクトルの最小値から成るベクトルが格納される D3DVECTOR2 型。
V1
処理の基になる D3DVECTOR2 型。
V2
処理の基になる D3DVECTOR2 型。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DERR_OUTOFVIDEOMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

参照

D3DXVec2Maximize


D3DXVec2Normalize

2D ベクトルの正規化したベクトルを返す。

D3DXVec2Normalize( _
    VOut As D3DVECTOR2, _
    v As D3DVECTOR2)

パラメータ

VOut
演算結果である正規化したベクトルが格納される D3DVECTOR2 型。
v
処理の基になる D3DVECTOR2 型。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DERR_OUTOFVIDEOMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。


D3DXVec2Scale

2D ベクトルをスケーリングする。

D3DXVec2Scale( _
    VOut As D3DVECTOR2, _
    V1 As D3DVECTOR2, _
    s As Single)

パラメータ

VOut
演算結果であるスケーリングされたベクトルが格納される D3DVECTOR2 型。
V1
処理の基になる D3DVECTOR2 型。
s
スケーリング値。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DERR_OUTOFVIDEOMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

参照

D3DXVec2Add、D3DXVec2Subtract


D3DXVec2Subtract

2 つの 2D ベクトルを減算する。

D3DXVec2Subtract( _
    VOut As D3DVECTOR2, _
    V1 As D3DVECTOR2, _
    V2 As D3DVECTOR2)

パラメータ

VOut
演算結果である 2 つのベクトルの差が格納される D3DVECTOR2 型。
V1
処理の基になる D3DVECTOR2 型。
V2
処理の基になる D3DVECTOR2 型。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DERR_OUTOFVIDEOMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

参照

D3DXVec2Add、D3DXVec2Scale


D3DXVec2Transform

指定された行列により 2D ベクトルをトランスフォームする。

D3DXVec2Transform( _
    VOut As D3DVECTOR4, _
    V1 As D3DVECTOR2, _
    M As D3DMATRIX)

パラメータ

VOut
演算結果であるトランスフォームされたベクトルが格納される D3DVECTOR4 型。
V1
処理の基になる D3DVECTOR2 型。
M
処理の基になる D3DMATRIX 型。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DERR_OUTOFVIDEOMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

この関数は、ベクトル V1 (x, y, 0, 1) を行列 M でトランスフォームする。

参照

D3DXVec2TransformCoord、D3DXVec2TransformNormal


D3DXVec2TransformCoord

指定された行列により 2D ベクトルをトランスフォームし、その結果を w = 1 に射影する。

D3DXVec2TransformCoord( _
    VOut As D3DVECTOR2, _
    V1 As D3DVECTOR2, _
    M As D3DMATRIX)

パラメータ

VOut
演算結果であるトランスフォームされたベクトルが格納される D3DVECTOR2 型。
V1
処理の基になる D3DVECTOR2 型。
M
処理の基になる D3DMATRIX 型。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DERR_OUTOFVIDEOMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

この関数は、ベクトル V1 (x, y, 0, 1) を行列 M でトランスフォームし、結果を w=1 に射影する。

参照

D3DXVec2Transform、D3DXVec2TransformNormal


D3DXVec2TransformNormal

指定された行列により 2D ベクトル法線をトランスフォームする。

D3DXVec2TransformNormal( _
    VOut As D3DVECTOR2, _
    V1 As D3DVECTOR2, _
    M As D3DMATRIX)

パラメータ

VOut
演算結果であるトランスフォームされたベクトルが格納される D3DVECTOR2 型。
V1
処理の基になる D3DVECTOR2 型。
M
処理の基になる D3DMATRIX 型。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DERR_OUTOFVIDEOMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

この関数は、ベクトル V1 のベクトル法線 (x, y, 0, 0) を行列 M でトランスフォームする。

参照

D3DXVec2Transform、D3DXVec2TransformCoord


D3DXVec3Add

2 つの 3D ベクトルを追加する。

D3DXVec3Add( _
    VOut As D3DVECTOR, _
    V1 As D3DVECTOR, _
    V2 As D3DVECTOR)

パラメータ

VOut
演算結果である 2 つの 3D ベクトルの和が格納される D3DVECTOR 型。
V1
処理の基になる D3DVECTOR 型。
V2
処理の基になる D3DVECTOR 型。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DERR_OUTOFVIDEOMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

参照

D3DXVec3Subtract、D3DXVec3Scale


D3DXVec3BaryCentric

指定した 3D ベクトルを使用して、重心座標のポイントを返す。

D3DXVec3BaryCentric( _
    VOut As D3DVECTOR, _
    V1 As D3DVECTOR, _
    V2 As D3DVECTOR, _
    V3 As D3DVECTOR, _
    f As Single, _
    g As Single)

パラメータ

VOut
演算結果である重心座標のベクトルが格納される D3DVECTOR 型。
V1
処理の基になる D3DVECTOR 型。
V2
処理の基になる D3DVECTOR 型。
V3
処理の基になる D3DVECTOR 型。
f
加重係数。「注意」を参照すること。
g
加重係数。「注意」を参照すること。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DERR_OUTOFVIDEOMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

D3DXVec3BaryCentric 関数は、三角形の実際の位置とは関係なく、三角形の内部および周辺のポイントを認識する手段を提供する。この関数は、次の方程式を使用して、結果として描画されるポイントを返す: V1 + f(V2-V1) + g(V3-V1)。

平面 V1V2V3 のポイントはいずれも、重心座標 (f,g) で表すことができる。パラメータ f は、V2 の結果に対する加重を制御し、パラメータ g は、V3 の結果に対する加重を制御する。最後に、1-f-g は V1 の結果に対する加重を制御する。

次の関係に注意すること。

  • (f>=0 And g>=0 And 1-f-g>=0) の場合、ポイントは三角形 V1V2V3 の中にある。
  • (f==0 And g>=0 And 1-f-g>=0) の場合、ポイントは線 V1V3 上にある。
  • (f>=0 And g==0 And 1-f-g>=0) の場合、ポイントは線 V1V2 上にある。
  • (f>=0 And g>=0 And 1-f-g==0) の場合、ポイントは線 V2V3 上にある。

重心座標は一般座標の 1 つの形式である。このコンテキストでは、重心座標を使用して座標システムの変化を簡単に表している。デカルト座標で TRUE のものは、重心座標でも TRUE である。


D3DXVec3Cross

2 つの 3D ベクトルの外積を計算する。

D3DXVec3Cross( _
    VOut As D3DVECTOR, _
    V1 As D3DVECTOR, _
    V2 As D3DVECTOR)

パラメータ

VOut
演算結果である 2 つの 3D ベクトルの外積が格納される D3DVECTOR 型。
V1
処理の基になる D3DVECTOR 型。
V2
処理の基になる D3DVECTOR 型。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DERR_OUTOFVIDEOMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

この関数は、次のコードを使用して外積を計算する。

Dim VOut As D3DVECTOR

VOut.x = V1.y * V2.z - V1.z * V2.y
VOut.y = V1.z * V2.x - V1.x * V2.z
VOut.z = V1.x * V2.y - V1.y * V2.x

参照

D3DXVec3Dot


D3DXVec3Dot

2 つの 3D ベクトルの内積を判定する。

D3DXVec3Dot( _
    V1 As D3DVECTOR, _
    V2 As D3DVECTOR) As Single

パラメータ

V1
処理の基になる D3DVECTOR 型。
V2
処理の基になる D3DVECTOR 型。

戻り値

内積。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DERR_OUTOFVIDEOMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

参照

D3DXVec3Cross


D3DXVec3Hermite

指定された 3D ベクトルを使用してエルミートのスプライン補間を実行する。

D3DXVec3Hermite( _
    VOut As D3DVECTOR, _
    V1 As D3DVECTOR, _
    T1 As D3DVECTOR, _
    V2 As D3DVECTOR, _
    T2 As D3DVECTOR, _
    s As Single)

パラメータ

VOut
演算結果であるエルミートのスプライン補間が格納される D3DVECTOR 型。
V1
処理の基になる D3DVECTOR 型。位置ベクトルを示す。
T1
処理の基になる D3DVECTOR 型。接線ベクトルを示す。
V2
処理の基になる D3DVECTOR 型。位置ベクトルを示す。
T2
処理の基になる D3DVECTOR 型。接線ベクトルを示す。
s
加重係数。「注意」を参照すること。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DERR_OUTOFVIDEOMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

関数 D3DXVec3Hermite は、エルミートのスプライン補間を使用して、(positionA, tangentA) から (positionB, tangentB) までを補間する。この関数は、位置 V1 と接線 T1 の間 (s が 0 の場合) と、位置 V2 と接線 T2 の間 (s が 1 の場合) を補間する。

カーブはすべての制御点を通って実行されるので、エルミートのスプラインはアニメーションの制御に便利である。また、位置および接線は各セグメントの最後に明示的に指定されるので、開始位置および接線が最後のセグメントの終わり値に一致していることが確認されている限り、C2 の継続的なカーブの作成は簡単である。


D3DXVec3Length

3D ベクトルの長さを返す。

D3DXVec3Length( _
    v As D3DVECTOR) As Single

パラメータ

v
処理の基になる D3DVECTOR 型。

戻り値

ベクトルの長さ。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DERR_OUTOFVIDEOMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

参照

D3DXVec3LengthSq


D3DXVec3LengthSq

3D ベクトルの長さの 2 乗を返す。

D3DXVec3LengthSq( _
    v As D3DVECTOR) As Single

パラメータ

v
処理の基になる D3DVECTOR 型。

戻り値

ベクトルの 2 乗された長さ。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DERR_OUTOFVIDEOMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

参照

D3DXVec3Length


D3DXVec3Lerp

2 つの 3D ベクトル間の線形補間を実行する。

D3DXVec3Lerp( _
    VOut As D3DVECTOR, _
    V1 As D3DVECTOR, _
    V2 As D3DVECTOR, _
    s As Single)

パラメータ

VOut
演算結果である線形補間が格納される D3DVECTOR 型。
V1
処理の基になる D3DVECTOR 型。
V2
処理の基になる D3DVECTOR 型。
s
ベクトル間を線形補間するパラメータ。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DERR_OUTOFVIDEOMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

この関数は、次の数式に基づいて線形補間を実行する: V1 + s(V2-V1)。


D3DXVec3Maximize

2 つの 3D ベクトルの最大値で構成される 3D ベクトルを返す。

D3DXVec3Maximize( _
    VOut As D3DVECTOR, _
    V1 As D3DVECTOR, _
    V2 As D3DVECTOR)

パラメータ

VOut
演算結果である、2 つのベクトルの最大値から成るベクトルが格納される D3DVECTOR 型。
V1
処理の基になる D3DVECTOR 型。
V2
処理の基になる D3DVECTOR 型。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DERR_OUTOFVIDEOMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

参照

D3DXVec3Minimize


D3DXVec3Minimize

2 つの 3D ベクトルの最小値で構成される 3D ベクトルを返す。

D3DXVec3Minimize( _
    VOut As D3DVECTOR, _
    V1 As D3DVECTOR, _
    V2 As D3DVECTOR)

パラメータ

VOut
演算結果である、2 つのベクトルの最小値から成るベクトルが格納される D3DVECTOR 型。
V1
処理の基になる D3DVECTOR 型。
V2
処理の基になる D3DVECTOR 型。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DERR_OUTOFVIDEOMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

参照

D3DXVec3Maximize


D3DXVec3Normalize

3D ベクトルの正規化したベクトルを返す。

D3DXVec3Normalize( _
    VOut As D3DVECTOR, _
    v As D3DVECTOR)

パラメータ

VOut
演算結果である、指定された正規化したベクトルが格納される D3DVECTOR 型。
v
処理の基になる D3DVECTOR 型。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DERR_OUTOFVIDEOMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。


D3DXVec3Project

オブジェクト空間からスクリーン空間にベクトルを射影する。

D3DXVec3Project( _
    VOut As D3DVECTOR, _
    V As D3DVECTOR, _
    Viewport As D3DVIEWPORT8, _
    Projection As D3DMATRIX, _
    View As D3DMATRIX, _
    World As D3DMATRIX)

パラメータ

VOut
演算結果である、オブジェクト空間からスクリーン空間に射影されたベクトルが格納される D3DVECTOR 型。
V
処理の基になる D3DVECTOR 型。
Viewport
ビューポートを表す D3DVIEWPORT8 型。
Projection
射影行列を表す D3DMATRIX 型。
View
ビュー行列を表す D3DMATRIX 型。
World
ワールド行列を表す D3DMATRIX 型。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DERR_OUTOFVIDEOMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

参照

D3DXVec3Unproject


D3DXVec3Scale

3D ベクトルをスケーリングする。

D3DXVec3Scale( _
    VOut As D3DVECTOR2, _
    V1 As D3DVECTOR2, _
    s As Single)

パラメータ

VOut
演算結果であるスケーリングされたベクトルが格納される D3DVECTOR 型。
V1
処理の基になる D3DVECTOR 型。
s
スケーリング値。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DERR_OUTOFVIDEOMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

参照

D3DXVec3Add、D3DXVec3Subtract


D3DXVec3Subtract

2 つの 3D ベクトルを減算する。

D3DXVec3Subtract( _
    VOut As D3DVECTOR, _
    V1 As D3DVECTOR, _
    V2 As D3DVECTOR)

パラメータ

VOut
演算結果である 2 つのベクトルの差が格納される D3DVECTOR 型。
V1
処理の基になる D3DVECTOR 型。
V2
処理の基になる D3DVECTOR 型。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DERR_OUTOFVIDEOMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

参照

D3DXVec3Add、D3DXVec3Scale


D3DXVec3Transform

指定された行列により 3D ベクトルをトランスフォームする。

D3DXVec3Transform( _
    VOut As D3DVECTOR4, _
    V1 As D3DVECTOR, _
    M As D3DMATRIX)

パラメータ

VOut
演算結果であるトランスフォームされたベクトルが格納される D3DVECTOR4 型。
V1
処理の基になる D3DVECTOR 型。
M
処理の基になる D3DMATRIX 型。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DERR_OUTOFVIDEOMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

この関数は、ベクトル V1 (x, y, z, 1) を行列 M でトランスフォームする。

参照

D3DXVec3TransformCoord、D3DXVec3TransformNormal


D3DXVec3TransformCoord

指定された行列により 3D ベクトルをトランスフォームし、その結果を w = 1 に射影する。

D3DXVec3TransformCoord( _
    VOut As D3DVECTOR, _
    V1 As D3DVECTOR, _
    M As D3DMATRIX)

パラメータ

VOut
演算結果であるトランスフォームされたベクトルが格納される D3DVECTOR 型。
V1
処理の基になる D3DVECTOR 型。
M
処理の基になる D3DMATRIX 型。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DERR_OUTOFVIDEOMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

この関数は、ベクトル V1 (x, y, z, 1) を行列 M でトランスフォームし、結果を w=1 に射影する。

参照

D3DXVec3Transform、D3DXVec3TransformNormal


D3DXVec3TransformNormal

指定された行列により 3D ベクトル法線をトランスフォームする。

D3DXVec3TransformNormal( _
    VOut As D3DVECTOR, _
    V1 As D3DVECTOR, _
    M As D3DMATRIX)

パラメータ

VOut
演算結果であるトランスフォームされたベクトルが格納される D3DVECTOR 型。
V1
処理の基になる D3DVECTOR 型。
M
処理の基になる D3DMATRIX 型。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DERR_OUTOFVIDEOMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

この関数は、ベクトル V1 のベクトル法線 (x, y, z, 0) を行列 M でトランスフォームする。

非アフィン行列を使って法線をトランスフォームする場合は、座標のトランスフォームに使用する行列の逆行列の転置行列をこの関数に渡すことが望ましい。


D3DXVec3Unproject

スクリーン空間からオブジェクト空間にベクトルを射影する。

D3DXVec3Unproject( _
    VOut As D3DVECTOR, _
    V As D3DVECTOR, _
    Viewport As D3DVIEWPORT8, _
    Projection As D3DMATRIX, _
    View As D3DMATRIX, _
    World As D3DMATRIX)

パラメータ

VOut
演算結果である、スクリーン空間からオブジェクト空間に射影されたベクトルが格納される D3DVECTOR 型。
V
処理の基になる D3DVECTOR 型。
Viewport
ビューポートを表す D3DVIEWPORT8 型。
Projection
射影行列を表す D3DMATRIX 型。
View
ビュー行列を表す D3DMATRIX 型。
World
ワールド行列を表す D3DMATRIX 型。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DERR_OUTOFVIDEOMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

参照

D3DXVec3Project


D3DXVec4Add

2 つの 4D ベクトルを追加する。

D3DXVec4Add( _
    VOut As D3DVECTOR4, _
    V1 As D3DVECTOR4, _
    V2 As D3DVECTOR4)

パラメータ

VOut
演算結果である 2 つのベクトルの和が格納される D3DVECTOR4 型。
V1
処理の基になる D3DVECTOR4 型。
V2
処理の基になる D3DVECTOR4 型。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DERR_OUTOFVIDEOMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

参照

D3DXVec4Subtract、D3DXVec4Scale


D3DXVec4BaryCentric

指定した 4D ベクトルを使用して、重心座標のポイントを返す。

D3DXVec4BaryCentric( _
    VOut As D3DVECTOR4, _
    V1 As D3DVECTOR4, _
    V2 As D3DVECTOR4, _
    V3 As D3DVECTOR4, _
    f As Single, _
    g As Single)

パラメータ

VOut
演算結果である重心座標のベクトルが格納される D3DVECTOR4 型。
V1
処理の基になる D3DVECTOR4 型。
V2
処理の基になる D3DVECTOR4 型。
V3
処理の基になる D3DVECTOR4 型。
f
加重係数。「注意」を参照すること。
g
加重係数。「注意」を参照すること。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DERR_OUTOFVIDEOMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

D3DXVec4BaryCentric 関数は、三角形の実際の位置とは関係なく、三角形の内部および周辺のポイントを認識する手段を提供する。この関数は、次の方程式を使用して、結果として描画されるポイントを返す: V1 + f(V2-V1) + g(V3-V1)。

平面 V1V2V3 のポイントはいずれも、重心座標 (f,g) で表すことができる。パラメータ f は、V2 の結果に対する加重を制御し、パラメータ g は、V3 の結果に対する加重を制御する。最後に、1-f-g は V1 の結果に対する加重を制御する。

次の関係に注意すること。

  • (f>=0 And g>=0 And 1-f-g>=0) の場合、ポイントは三角形 V1V2V3 の中にある。
  • (f==0 And g>=0 And 1-f-g>=0) の場合、ポイントは線 V1V3 上にある。
  • (f>=0 And g==0 And 1-f-g>=0) の場合、ポイントは線 V1V2 上にある。
  • (f>=0 And g>=0 And 1-f-g==0) の場合、ポイントは線 V2V3 上にある。

重心座標は一般座標の 1 つの形式である。このコンテキストでは、重心座標を使用して座標システムの変化を簡単に表している。デカルト座標で TRUE のものは、重心座標でも TRUE である。


D3DXVec4CatmullRom

指定された 4D ベクトルを使用して Catmull-Rom 補間を実行する。

D3DXVec4CatmullRom( _
    VOut As D3DVECTOR4, _
    V0 As D3DVECTOR4, _
    V1 As D3DVECTOR4, _
    V2 As D3DVECTOR4, _
    V3 As D3DVECTOR4, _
    s As Single)

パラメータ

VOut
演算結果が格納される D3DVECTOR4 型。
V0
D3DVECTOR4 型。位置ベクトルを示す。
V1
D3DVECTOR4 型。位置ベクトルを示す。
V2
D3DVECTOR4 型。位置ベクトルを示す。
V3
D3DVECTOR4 型。位置ベクトルを示す。
s
加重係数。「注意」を参照すること。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DERR_OUTOFVIDEOMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

D3DXVec4CatmullRom 関数は、Catmull-Rom 補間を使用して、位置 V1 (s が 0 の場合) の間と、位置 V2 (s が 1 の場合) の間の補間を行う。


D3DXVec4Cross

4D の外積を計算する。

D3DXVec4Cross( _
    VOut As D3DVECTOR4, _
    V1 As D3DVECTOR4, _
    V2 As D3DVECTOR4, _
    V3 As D3DVECTOR4)

パラメータ

VOut
演算結果である外積が格納される D3DVECTOR4 型。
V1
処理の基になる D3DVECTOR4 型。
V2
処理の基になる D3DVECTOR4 型。
V3
処理の基になる D3DVECTOR4 型。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DERR_OUTOFVIDEOMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

参照

D3DXVec4Dot


D3DXVec4Dot

2 つの 4D ベクトルの内積を判定する。

D3DXVec4Dot( _
    V1 As D3DVECTOR4, _
    V2 As D3DVECTOR4) As Single

パラメータ

V1
処理の基になる D3DVECTOR4 型。
V2
処理の基になる D3DVECTOR4 型。

戻り値

内積。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DERR_OUTOFVIDEOMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

参照

D3DXVec4Cross


D3DXVec4Hermite

指定された 4D ベクトルを使用してエルミートのスプライン補間を実行する。

D3DXVec4Hermite( _
    VOut As D3DVECTOR4, _
    V1 As D3DVECTOR, _
    T1 As D3DVECTOR, _
    V2 As D3DVECTOR, _
    T2 As D3DVECTOR, _
    s As Single)

パラメータ

VOut
演算結果であるエルミートのスプライン補間が格納される D3DVECTOR4 型。
V1
処理の基になる D3DVECTOR 型。位置ベクトルを示す。
T1
処理の基になる D3DVECTOR4 型。接線ベクトルを示す。
V2
処理の基になる D3DVECTOR 型。位置ベクトルを示す。
T2
処理の基になる D3DVECTOR4 型。接線ベクトルを示す。
s
加重係数。「注意」を参照すること。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DERR_OUTOFVIDEOMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

関数 D3DXVec4Hermite は、エルミートのスプライン補間を使用して、(positionA, tangentA) から (positionB, tangentB) までを補間する。この関数は、位置 V1 と接線 T1 の間 (s が 0 の場合) と、位置 V2 と接線 T2 の間 (s が 1 の場合) を補間する。

カーブはすべての制御点を通って実行されるので、エルミートのスプラインはアニメーションの制御に便利である。また、位置および接線は各セグメントの最後に明示的に指定されるので、開始位置および接線が最後のセグメントの終わり値に一致していることが確認されている限り、C2 の継続的なカーブの作成は簡単である。


D3DXVec4Length

4D ベクトルの長さを返す。

D3DXVec4Length( _
    v As D3DVECTOR4) As Single

パラメータ

v
処理の基になる D3DVECTOR4 型。

戻り値

ベクトルの長さ。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DERR_OUTOFVIDEOMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

参照

D3DXVec4LengthSq


D3DXVec4LengthSq

4D ベクトルの長さの 2 乗を返す。

D3DXVec4LengthSq( _
    v As D3DVECTOR4) As Single

パラメータ

v
処理の基になる D3DVECTOR4 型。

戻り値

ベクトルの 2 乗された長さ。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DERR_OUTOFVIDEOMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

参照

D3DXVec4Length


D3DXVec4Lerp

2 つの 4D ベクトル間の線形補間を実行する。

D3DXVec4Lerp( _
    VOut As D3DVECTOR4, _
    V1 As D3DVECTOR4, _
    V2 As D3DVECTOR4, _
    s As Single)

パラメータ

VOut
演算結果である線形補間が格納される D3DVECTOR4 型。
V1
処理の基になる D3DVECTOR4 型。
V2
処理の基になる D3DVECTOR4 型。
s
ベクトル間を線形補間するパラメータ。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DERR_OUTOFVIDEOMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

この関数は、次の数式に基づいて線形補間を実行する: V1 + s(V2-V1)。


D3DXVec4Maximize

2 つの 4D ベクトルの最大値で構成される 4D ベクトルを返す。

D3DXVec4Maximize( _
    VOut As D3DVECTOR4, _
    V1 As D3DVECTOR4, _
    V2 As D3DVECTOR4)

パラメータ

VOut
演算結果である、2 つのベクトルの最大値から成るベクトルが格納される D3DVECTOR4 型。
V1
処理の基になる D3DVECTOR4 型。
V2
処理の基になる D3DVECTOR4 型。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DERR_OUTOFVIDEOMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

参照

D3DXVec4Minimize


D3DXVec4Minimize

2 つの 4D ベクトルの最小値で構成される 4D ベクトルを返す。

D3DXVec4Minimize( _
    VOut As D3DVECTOR4, _
    V1 As D3DVECTOR4, _
    V2 As D3DVECTOR4)

パラメータ

VOut
演算結果である、2 つのベクトルの最小値から成るベクトルが格納される D3DVECTOR4 型。
V1
処理の基になる D3DVECTOR4 型。
V2
処理の基になる D3DVECTOR4 型。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DERR_OUTOFVIDEOMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

参照

D3DXVec4Maximize


D3DXVec4Normalize

4D ベクトルの正規化したベクトルを返す。

D3DXVec4Normalize( _
    VOut As D3DVECTOR4, _
    v As D3DVECTOR4)

パラメータ

VOut
演算結果である正規化したベクトルが格納される D3DVECTOR4 型。
v
処理の基になる D3DVECTOR4 型。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DERR_OUTOFVIDEOMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。


D3DXVec4Scale

4D ベクトルをスケーリングする。

D3DXVec4Scale( _
    VOut As D3DVECTOR4, _
    V1 As D3DVECTOR4, _
    s As Single)

パラメータ

VOut
演算結果であるスケーリングされたベクトルが格納される D3DVECTOR4 型。
V1
処理の基になる D3DVECTOR4 型。
s
スケーリング値。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DERR_OUTOFVIDEOMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

参照

D3DXVec4Add、D3DXVec4Subtract


D3DXVec4Subtract

2 つの 4D ベクトルを減算する。

D3DXVec4Subtract( _
    VOut As D3DVECTOR4, _
    V1 As D3DVECTOR4, _
    V2 As D3DVECTOR4)

パラメータ

VOut
演算結果である 2 つのベクトルの差が格納される D3DVECTOR4 型。
V1
処理の基になる D3DVECTOR4 型。
V2
処理の基になる D3DVECTOR4 型。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DERR_OUTOFVIDEOMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

参照

D3DXVec3Add、D3DXVec3Scale


D3DXVec4Transform

指定された行列により 4D ベクトルをトランスフォームする。

D3DXVec4Transform( _
    VOut As D3DVECTOR4, _
    V1 As D3DVECTOR4, _
    M As D3DMATRIX)

パラメータ

VOut
演算結果であるトランスフォームされた 4D ベクトルが格納される D3DVECTOR4 型。
V1
処理の基になる D3DVECTOR4 型。
M
処理の基になる D3DMATRIX 型。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

D3DERR_INVALIDCALL
D3DERR_OUTOFVIDEOMEMORY

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。


型

ここでは、Direct3DX ユーティリティ ライブラリで使用される以下の型について説明する。

  • D3DXATTRIBUTERANGE
  • D3DXATTRIBUTEWEIGHTS
  • D3DXBONECOMBINATION
  • D3DXDECLARATOR
  • D3DXIMAGE_INFO
  • D3DXMATERIAL
  • D3DXRTS_DESC


D3DXATTRIBUTERANGE

テーブルの属性値を格納する。

Type D3DXATTRIBUTERANGE
    AttribId As Long
    FaceCount As Long
    FaceStart As Long
    VertexCount As Long
    VertexStart As Long
End Type

メンバ

AttribId
属性テーブルの識別子。
FaceCount
面の数。
FaceStart
開始面。
VertexCount
頂点の数。
VertexStart
開始頂点。

注意

属性テーブルは、異なるテクスチャ、レンダリング ステート、マテリアルなどによって描画する必要があるメッシュの領域を識別するために使用される。さらにアプリケーションは、属性テーブルを使用し、フレームの描画時に所定の属性識別子 (AttribId) を描画しないことによって、メッシュの一部を隠すことができる。

参照

D3DXBaseMesh.DrawSubset


D3DXATTRIBUTEWEIGHTS

頂点の成分の重み付けを指定する。

Type D3DXATTRIBUTEWEIGHTS
    Boundary As Single
    diffuse As Single
    Normal As Single
    position As Single
    specular As Single
    Tex(0 To 7) As Single
End Type

メンバ

Boundary
境界成分の加重。
diffuse
ディフューズ成分の加重。
Normal
法線成分の加重。
position
位置成分の加重。
specular
スペキュラ成分の加重。
Tex
テクスチャ座標の加重。

注意

この型は、エッジをたたむ間の相対コストを計算する場合に、単純化の操作が頂点データを扱う方法を記述する。たとえば、Normal フィールドが 0.0 の場合、単純化の操作ではエッジをたたむことに関するエラーを計算する際に頂点法線成分が無視される。ただし、Normal フィールドが 1.0 の場合は、単純化の操作で頂点法線成分が使用される。Normal フィールドが 2.0 の場合は、エラーの数が 2 倍になり、Normal フィールドが 4.0 の場合はエラーの数が 4 倍になる。以下同様に続く。

参照

D3DX8.CreateSPMesh、D3DX8.GeneratePMesh、D3DX8.SimplifyMesh


D3DXBONECOMBINATION

属性とボーンの組み合わせが同じメッシュのサブセットを記述する。

Type D3DXBONECOMBINATION
    AttribId As Long
    FaceCount As Long
    FaceStart As Long
    VertexCount As Long
    VertexStart As Long
End Type

メンバ

AttribId
属性テーブルの識別子。
FaceCount
面の数。
FaceStart
開始面。
VertexCount
頂点の数。
VertexStart
開始頂点。

注意

D3DXBONECOMBINATION によって記述されたメッシュのサブセットは、1 回の描画呼び出しでレンダリングできる。


D3DXDECLARATOR

宣言子の配列を格納する。

Type D3DXDECLARATOR
    value(0 To 31) As Long
End Type

メンバ

value
頂点の頂点フォーマットを記述する、宣言子の配列。

参照

D3DX8.DeclaratorFromFVF、D3DX8.FVFFromDeclarator


D3DXIMAGE_INFO

イメージ ファイルのオリジナルの内容の記述を返すために使用する。

Type D3DXIMAGE_INFO
    Depth As Long
    Height As Long
    MipLevels As Long
    Width As Long
    Format As Long
End Type

メンバ

Depth
オリジナル イメージの幅 (ピクセル単位)。
Height
オリジナル イメージの高さ (ピクセル単位)。
MipLevels
オリジナル イメージの深度 (ピクセル単位)。
Width
オリジナル イメージのミップ レベルの数。
Format
オリジナル イメージのデータを最も厳密に記述する CONST_D3DFORMAT 列挙型からの値。

参照

D3DX8.DeclaratorFromFVF、D3DX8.FVFFromDeclarator


D3DXMATERIAL

Microsoft® DirectX® (.x) ファイルに保存されたマテリアル情報を返す。

Type D3DXMATERIAL
    Material As D3DMATERIAL8
    TextureFilename As String
End Type

メンバ

Material
マテリアルの型を記述する D3DMATERIAL8 構造体。
TextureFilename
テクスチャのファイル名を指定する String 値。

注意

D3DX8.LoadMeshFromX メソッドおよび D3DX8.LoadMeshFromXof メソッドは D3DXMATERIAL 型の配列を返す。この型は、メッシュに含まれる各マテリアルのテクスチャについて、マテリアルのカラーと名前を指定する。アプリケーションは、さらにテクスチャをロードする必要がある。

参照

D3DX8.LoadMeshFromX、D3DX8.LoadMeshFromXof


D3DXRTS_DESC

レンダリング サーフェスを記述する。

Type D3DXRTS_DESC
    Width As Long
    Height As Long
    format As Long
    DepthStencil As Long
    DepthStencilFormat As Long
End Type

メンバ

Width
レンダリング サーフェスの幅 (ピクセル単位)。
Height
レンダリング サーフェスの高さ (ピクセル単位)。
format
レンダリング サーフェスのピクセル フォーマットを記述する CONST_D3DFORMAT 列挙型のメンバ。
DepthStencil
TRUE の場合、レンダリング サーフェスは深度ステンシル サーフェスをサポートする。それ以外の場合、このメンバは FALSE に設定される。
DepthStencilFormat
DepthStencil が TRUE の場合、このパラメータはレンダリング サーフェスの深度ステンシル フォーマットを記述する D3DFORMAT 列挙型のメンバである。

参照

D3DXRenderToSurface.GetDesc


列挙

ここでは、Direct3DX ユーティリティ ライブラリで使用される以下の列挙について記述する。

  • CONST_D3DXASM
  • CONST_D3DXENUM
  • CONST_D3DXERR
  • CONST_D3DXMESH
  • CONST_D3DXMESHMISC
  • CONST_D3DXMESHOPT
  • CONST_D3DXMESHSIMP
  • CONST_DTFLAGS


CONST_D3DXASM

シェーダ アセンブリ フラグを定義する。

Enum CONST_D3DXMESHMISC
    D3DXASM_DEBUG          = 1
    D3DXASM_SKIPVALIDATION = 2
End Enum

定数

D3DXASM_DEBUG
デバッグ情報をアセンブルしたシェーダにコメントとして挿入する。
D3DXASM_SKIPVALIDATION
生成されたコードに対して既知の能力および制約の検証をしない。このオプションは、動作することがわかっているシェーダをアセンブルする場合 (たとえば、前にこのオプションを使用せずにシェーダをアセンブルしたことがある場合) にのみ使用することを勧める。

参照

D3DX8.AssembleShader、D3DX8.AssembleShaderFromFile


CONST_D3DXENUM

イメージ フィルタなど、Direct3DX のその他のフラグを定義する。

Enum CONST_D3DXENUM
    D3DX_FILTER_NONE     =      0
    D3DX_FILTER_POINT    =      1
    D3DX_FILTER_LINEAR   =      2
    D3DX_FILTER_TRIANGLE =      3
    D3DX_FILTER_BOX      =      4
    D3DX_FILTER_MIRROR_U =  65536 (&H10000)
    D3DX_FILTER_MIRROR_V = 131072 (&H20000)
    D3DX_FILTER_MIRROR   = 196608 (&H30000)
    D3DX_FILTER_DITHER   = 524288 (&H80000)
    D3DX_DEFAULT         =     -1 (&HFFFFFFFF)
End Enum

定数

D3DX_FILTER_NONE
スケーリングまたはフィルタリングを行わない。ソース イメージの境界の外側にあるピクセルは透明な黒であると見なされる。
D3DX_FILTER_POINT
各転送先ピクセルは、最も近いピクセルをソース イメージからサンプリングすることにより計算される。
D3DX_FILTER_LINEAR
各転送先ピクセルは、ソース イメージ内の最も近いピクセルどうしを線形補間することにより計算される。このフィルタは、各軸のスケールが 2 未満の場合に最も効率よく機能する。
D3DX_FILTER_TRIANGLE
ソース イメージ内の各ピクセルが、転送先イメージに等しく反映される。これは、最も処理に時間のかかるフィルタである。
D3DX_FILTER_BOX
各ピクセルは、ソースイメージ内の 2 × 2 (× 2) のサイズのボックスに含まれるピクセルの平均を算出することにより計算される。このフィルタは、ミップ マップを使用する場合のように、転送先の次元がソースの半分の場合のみ機能する。
D3DX_FILTER_MIRROR_U
u 軸のテクスチャのエッジから離れているピクセルをラッピングせずに、ミラーリングするよう指定する。
D3DX_FILTER_MIRROR_V
v 軸のテクスチャのエッジから離れているピクセルをラッピングせずに、ミラーリングするよう指定する。
D3DX_FILTER_MIRROR
このフラグを指定すると、D3DX_FILTER_MIRROR_U と D3DX_FILTER_MIRROR_V の両方のフラグを指定したことになる。
D3DX_FILTER_DITHER
4x4 順序付きディザ アルゴリズムを使用して、結果のイメージをディザ表示する。
D3DX_DEFAULT
列挙値またはハンドルであるパラメータに使用可能な定義済み値。このドキュメントでは、D3DX_DEFAULT を使用できる場所や、各状況での解釈方法について示す。

注意

有効なそれぞれのフィルタに、次のフラグの 1 つが含まれていなければならない。

  • D3DX_FILTER_BOX
  • D3DX_FILTER_LINEAR
  • D3DX_FILTER_NONE
  • D3DX_FILTER_POINT
  • D3DX_FILTER_TRIANGLE

さらに、論理和演算子を使用して、有効なフィルタと共に次に示すオプションのフラグを 0 個以上指定できる。

  • D3DX_FILTER_MIRROR
  • D3DX_FILTER_MIRROR_U
  • D3DX_FILTER_MIRROR_V

参照

D3DX8.FilterCubeTexture、D3DX8.FilterTexture、D3DX8.LoadSurfaceFromFile、D3DX8.LoadSurfaceFromFileInMemory、D3DX8.LoadSurfaceFromMemory、D3DX8.LoadSurfaceFromSurface


CONST_D3DXERR

システムで発生するエラー コードを定義する。これらのエラー コードの詳細については、「エラー コード」を参照すること。


CONST_D3DXMESH

メッシュの作成オプションを指定する。

Enum CONST_D3DXMESH
    D3DXMESH_32BIT        =        1
    D3DXMESH_DONOTCLIP    =        2
    D3DXMESH_POINTS       =        4
    D3DXMESH_RTPATCHES    =        8
    D3DXMESH_VB_SYSTEMMEM =       16 (&H10)
    D3DXMESH_VB_MANAGED   =       32 (&H20)
    D3DXMESH_VB_WRITEONLY =       64 (&H40)
    D3DXMESH_VB_DYNAMIC   =      128 (&H80)
    D3DXMESH_IB_SYSTEMMEM =      256 (&H100)
    D3DXMESH_SYSTEMMEM    =      272 (&H110)
    D3DXMESH_IB_MANAGED   =      512 (&H200)
    D3DXMESH_MANAGED      =      544 (&H220)
    D3DXMESH_WRITEONLY    =      816 (&H330)
    D3DXMESH_IB_WRITEONLY =     1024 (&H400)
    D3DXMESH_IB_DYNAMIC   =     2048 (&H800)
    D3DXMESH_DYNAMIC      =     2176 (&H880)
    D3DXMESH_VB_SHARE     =     4096 (&H1000)
    D3DXMESH_USEHWONLY    =     8192 (&H2000)
    D3DDEVCAPS_NPATCHES   = 16777216 (&H1000000)
End Enum

定数

D3DXMESH_32BIT
メッシュに、16 ビットではなく 32 ビットのインデックスを作成する。32 ビットのメッシュは、最大 2^32-1 の面と頂点を含むことができる。この定数は現在サポートされていないため、使用できない。
D3DXMESH_DONOTCLIP
頂点バッファおよびインデックス バッファに D3DUSAGE_DONOTCLIP 利用フラグを使用する。
D3DXMESH_POINTS
頂点バッファおよびインデックス バッファに D3DUSAGE_POINTS 利用フラグを使用する。
D3DXMESH_RTPATCHES
頂点バッファおよびインデックス バッファに D3DUSAGE_RTPATCHES 利用フラグを使用する。
D3DXMESH_VB_SYSTEMMEM
頂点バッファに D3DPOOL_SYSTEMMEM メモリ クラスを使用する。
D3DXMESH_VB_MANAGED
頂点バッファに D3DPOOL_MANAGED メモリ クラスを使用する。
D3DXMESH_VB_WRITEONLY
頂点バッファに D3DUSAGE_WRITEONLY 利用フラグを使用する。
D3DXMESH_VB_DYNAMIC
頂点バッファに D3DUSAGE_DYNAMIC 利用フラグを使用する。
D3DXMESH_DYNAMIC
D3DXMESH_VB_DYNAMIC と D3DXMESH_IB_DYNAMIC の両方を指定したことになる。
D3DXMESH_IB_SYSTEMMEM
インデックス バッファに D3DPOOL_SYSTEMMEM メモリ クラスを使用する。
D3DXMESH_SYSTEMMEM
D3DXMESH_VB_SYSTEMMEM と D3DXMESH_IB_SYSTEMMEM の両方を指定したことになる。
D3DXMESH_IB_MANAGED
インデックス バッファに D3DPOOL_MANAGED メモリ クラスを使用する。
D3DXMESH_MANAGED
D3DXMESH_VB_MANAGED と D3DXMESH_IB_MANAGED の両方を指定したことになる。
D3DXMESH_WRITEONLY
D3DXMESH_VB_WRITEONLY と D3DXMESH_IB_WRITEONLY の両方を指定したことになる。
D3DXMESH_IB_WRITEONLY
インデックス バッファに D3DUSAGE_WRITEONLY 利用フラグを使用する。
D3DXMESH_IB_DYNAMIC
インデックス バッファに D3DUSAGE_DYNAMIC 利用フラグを使用する。
D3DXMESH_VB_SHARE
コピーしたメッシュに頂点バッファを共有させる。これらのメッシュは、共有する頂点バッファにインデックス付けする個別のインデックス バッファを備える。
D3DXMESH_USEHWONLY
ハードウェア処理のみを使用する。このフラグは、ハードウェア処理デバイスに対してのみ指定する。混合モードのデバイスに対してこのフラグを指定すると、システムはハードウェアのみを使用するか、ハードウェアに処理能力がない場合は、ソフトウェアの能力を使用して概算する。

このフラグは、D3DXSkinMesh.ConvertToBlendedMesh メソッドのオプションとして指定された場合にのみ有効である。

D3DDEVCAPS_NPATCHES
このフラグを指定すると、メッシュの頂点バッファおよびインデックス バッファが D3DUSAGE_NPATCHES フラグを使用して作成されることになる。これは、Microsoft® Direct3D® の N パッチ拡張機能を使用してメッシュ オブジェクトをレンダリングする場合に必要となる。

参照

D3DX8.CreateMesh、D3DX8.CreateMeshFVF、D3DXBaseMesh.CloneMesh、D3DXBaseMesh.CloneMeshFVF、D3DXBaseMesh.GetOptions、D3DXPMesh.ClonePMesh、D3DXPMesh.ClonePMeshFVF 、 D3DXSPMesh.CloneMesh、D3DXSPMesh.CloneMeshFVF、D3DXSPMesh.ClonePMesh、D3DXSPMesh.ClonePMeshFVF、D3DXSPMesh.GetOptions


CONST_D3DXMESHMISC

その他のフラグを定義する。

Enum CONST_D3DXMESHMISC
    UNUSED16          = 65535 (&HFFFF)
    UNUSED32          =    -1 (&HFFFFFFFF)
    MAX_FVF_DECL_SIZE =    15
End Enum

定数

UNUSED16
この値は使用されない。
UNUSED32
この値は使用されない。
MAX_FVF_DECL_SIZE
宣言子の配列の上限。

参照

D3DX8.LoadMeshFromX、D3DX8.LoadMeshFromXof、D3DXMesh.Optimize


CONST_D3DXMESHOPT

メッシュに対して実行可能な最適化の種類を指定する。

Enum CONST_D3DXMESHOPT
    D3DXMESHOPT_COMPACT      =  1
    D3DXMESHOPT_ATTRSORT     =  2
    D3DXMESHOPT_VERTEXCACHE  =  4
    D3DXMESHOPT_IGNOREVERTS  = 16
    D3DXMESHOPT_SHAREVB      = 32
End Enum

定数

D3DXMESHOPT_COMPACT
面の順番を変更し、使用されていない頂点と面を削除する。
D3DXMESHOPT_ATTRSORT
属性バンドル ステートの変更を少なくし、D3DXBaseMesh.DrawSubset のパフォーマンスを強化するため、面の順番を変更して最適化を行う。
D3DXMESHOPT_VERTEXCACHE
面の順番を変更し、頂点キャッシュのキャッシュ ヒット率を向上させる。
D3DXMESHOPT_IGNOREVERTS
面のみ最適化する。頂点の最適化は行わない。
D3DXMESHOPT_SHAREVB
頂点バッファを共有する。

参照

D3DX8.LoadMeshFromX、D3DX8.LoadMeshFromXof、D3DXMesh.Optimize


CONST_D3DXMESHSIMP

メッシュの単純化オプションを指定する。

Enum CONST_D3DXMESHSIMP
    D3DXMESHSIMP_VERTEX = 1
    D3DXMESHSIMP_FACE   = 2
End Enum

定数

D3DXMESHSIMP_VERTEX
指定した数の頂点でメッシュが単純化される。
D3DXMESHSIMP_FACE
指定した数の面でメッシュが単純化される。

参照

D3DX8.GeneratePMesh、D3DX8.SimplifyMesh


CONST_DTFLAGS

テキストの描画に使用するフラグを定義する。

Enum CONST_DTFLAGS
    DT_LEFT                 =       0
    DT_TOP                  =       0
    DT_CENTER               =       1
    DT_RIGHT                =       2
    DT_VCENTER              =       4
    DT_BOTTOM               =       8
    DT_WORDBREAK            =      16 (&H10)
    DT_SINGLELINE           =      32 (&H20)
    DT_EXPANDTABS           =      64 (&H40)
    DT_TABSTOP              =     128 (&H80)
    DT_NOCLIP               =     256 (&H100)
    DT_EXTERNALLEADING      =     512 (&H200)
    DT_CALCRECT             =    1024 (&H400)
    DT_NOPREFIX             =    2048 (&H800)
    DT_INTERNAL             =    4096 (&H1000)
    DT_EDITCONTROL          =    8192 (&H2000)
    DT_PATH_ELLIPSIS        =   16384 (&H4000)
    DT_END_ELLIPSIS         =   32768 (&H8000)
    DT_MODIFYSTRING         =   65536 (&H10000)
    DT_RTLREADING           =  131072 (&H20000)
    DT_WORD_ELLIPSIS        =  262144 (&H40000)
    DT_NOFULLWIDTHCHARBREAK =  524288 (&H80000)
    DT_HIDEPREFIX           = 1048576 (&H100000)
    DT_PREFIXONLY           = 2097152 (&H200000)End Enum

定数

DT_LEFT
テキストを左端揃えにする。
DT_TOP
先頭行のテキストを両端揃えにする (1 行のみ)。
DT_CENTER
四角形内でテキストを水平方向で中央揃えにする。
DT_RIGHT
テキストを右端揃えにする。
DT_VCENTER
上下方向でテキストを中央揃えにする (1 行のみ)。
DT_BOTTOM
四角形の底部でテキストを両端揃えにする。この値は DT_SINGLELINE と組み合わせて使用しなければならない。
DT_WORDBREAK
語を分割する。語が DestRect パラメータで指定した四角形の端を超える場合、語と語の間で自動的に改行される。改行/行送りのシーケンスも改行となる。
DT_SINGLELINE
1 行のみにテキストを表示する。改行と行送りで新しい行に移らない。
DT_EXPANDTABS
タブ文字を拡張する。タブごとのデフォルトの文字数は 8 字である。DT_WORD_ELLIPSIS、DT_PATH_ELLIPSIS、および DT_END_ELLIPSIS は DT_EXPANDTABS と同時に使用することはできない。
DT_TABSTOP
タブ ストップを設定する。Format パラメータのビット 15-8 (低位語の高次バイト) により各タブの文字数を指定する。タブごとのデフォルトの文字数は 8 字である。DT_CALCRECT、DT_EXTERNALLEADING、DT_INTERNAL、DT_NOCLIP、および DT_NOPREFIX は DT_TABSTOP と同時に使用することはできない。
DT_NOCLIP
クリッピングせずに描画する。DrawTextW は DT_NOCLIP を使用する場合よりやや高速である。
DT_EXTERNALLEADING
行の高さにフォントの外部余白を含める。通常、外部余白は、テキストの行の高さには含まれない。
DT_CALCRECT
四角形の幅と高さを算出する。テキストが複数行ある場合、DrawTextW は パラメータ SrcRect が参照する四角形の幅を使用し、テキストの最後の行が含まれるよう四角形の底辺を延長する。テキストが 1 行だけの場合、DrawTextW は行の最後の文字が収まるよう四角形の右側の辺の位置を修正する。どちらの場合も、DrawTextW は整形されたテキストの高さを返すが、テキストは描画しない。
DT_NOPREFIX
プレフィクス文字の処理をオフにする。通常、DrawTextW はニーモニック プレフィクス文字の & (アンパサンド) を、その後に続く文字に下線を付ける命令として解釈し、ニーモニック プレフィクス文字が && と 2 つ続いた場合は、& を 1 つ出力する命令として解釈する。DT_NOPREFIX を指定することにより、この処理はオフになる。「DT_HIDEPREFIX」および「DT_PREFIXONLY」を参照すること。
DT_INTERNAL
システム フォントを使用してテキスト メトリクスを計算する。
DT_EDITCONTROL
マルチライン エディット コントロールのテキスト表示特性を複製する。特に、平均の文字幅はエディット コントロールと同じ方法で計算され、部分的に見える最後の行は表示されない。
DT_END_ELLIPSIS または DT_PATH_ELLIPSIS
省略記号を追加せずに文字列を切り捨て、指定した四角形に収まるようにする。DT_MODIFYSTRING フラグが指定されている場合を除き、文字列は修正されない。

DT_END_ELLIPSIS は文字列の最後で文字を切り捨てるために指定する。DT_PATH_ELLIPSIS は文字列の中間で文字を切り捨てるために指定する。文字列にバックスラッシュ (\) が含まれている場合、DT_PATH_ELLIPSIS は最後のバックスラッシュより後ろにあるテキストをできるだけ多く保持する。

DT_MODIFYSTRING
文字列を修正して表示されたテキストに合わせる。DT_END_ELLIPSIS または DT_PATH_ELLIPSIS が指定されている場合のみ、このフラグは有効となる。
DT_RTLREADING
ヘブライ語またはアラビア語のフォントが選択されている場合、読みの順序が双方向のテキストについて右から左の順に読むようテキストを表示する。デフォルトの読みの順序は、すべてのテキストで左から右となっている。
DT_WORD_ELLIPSIS
四角形に収まらないテキストを切り捨て、省略記号を追加する。
DT_NOFULLWIDTHCHARBREAK
Microsoft® Windows® 98、Windows 2000 の場合、DBCS (double-wide character string) で改行されないようにする。これにより改行ルールは SBCS (single-wide character string) 文字の設定と同じになる。たとえば、韓国語版 Windows でアイコン ラベルを読みやすくするために使用される。DT_WORDBREAK が指定されている場合のみ有効である。
DT_HIDEPREFIX
Windows 2000 では次のようになる。テキストに含まれるアンパサンド (&) プレフィクス文字を無視する。アンパサンドに続く文字に下線は付かないが、ほかのニーモニック プレフィクス文字はそのまま処理される。

例

入力文字列 :"A&bc&&d"

標準 :"Abc&d"

HIDEPREFIX:"Abc&d"

「DT_NOPREFIX」および「DT_PREFIXONLY」を参照すること。

DT_PREFIXONLY
Windows 2000 では次のようになる。アンパサンド (&) プレフィクス文字に続く文字の位置で、下線のみを描画する。文字列に含まれる文字は描画しない。

例

入力文字列 :"A&bc&&d"

標準 :"Abc&d"

PREFIXONLY: " "

「DT_NOPREFIX」および「DT_HIDEPREFIX」を参照すること。

参照

D3DXFont.DrawTextW、D3DX8.DrawText


エラー コード

エラーは負の値で表され、組み合わされることはない。以下は、Direct3DX ユーティリティ ライブラリに含まれるメソッドが返す可能性のある値を示している。メソッドから返される値については、それぞれの説明を参照すること。

D3DXERR_CANNOTATTRSORT
最適化テクニックとして、属性のソート (D3DXMESHOPT_ATTRSORT) はサポートされていない。
D3DXERR_CANNOTMODIFYINDEXBUFFER
インデックス バッファを変更できない。
D3DXERR_INVALIDDATA
データが無効である。
D3DXERR_INVALIDMESH
メッシュが無効である。
D3DXERR_SKINNINGNOTSUPPORTED
スキニングがサポートされていない。
D3DXERR_TOOMANYINFLUENCES
指定された影響が多すぎる。


Direct3DX シェーダ アセンブラ リファレンス

ここでは、Direct3DX ユーティリティ ライブラリが提供する頂点シェーダ アセンブラおよびピクセル シェーダ アセンブラのリファレンス情報を記述する。

  • 頂点シェーダ アセンブラ リファレンス
  • ピクセル シェーダ アセンブラ リファレンス

このマニュアルで使用されている構文の例はすべて、Direct3DX 頂点シェーダ アセンブラおよびピクセル シェーダ アセンブラを使用する場合のシェーダの記述方法を示すためのものである。


頂点シェーダ アセンブラ リファレンス

ここでは、頂点シェーダ アセンブラについてのリファレンス情報を記述する。リファレンス情報は次のカテゴリに分類されている。

  • レジスタ
  • 命令
  • 修飾子

頂点シェーダ アセンブラは、一連のレジスタおよびそのレジスタ上で実行できる処理群で構成されている。処理は、演算子と 1 つ以上の引数 (オペランド) で構成される命令として表現されている。


レジスタ

ここでは、Direct3DX 頂点シェーダ アセンブラが実装する入力および出力レジスタについてのリファレンス情報を記述する。説明するトピックは、次のとおりである。

  • 入力レジスタ
  • 出力レジスタ

すべてのレジスタは 4 成分浮動小数点ベクトルである。このマニュアルでは、ベクトルの要素は、x、y、z および w として指定するが、セマンティクスは指定されていない。


入力レジスタ

次の表は、Microsoft® DirectX® 8.0 の頂点シェーダが利用できる最低限の入力レジスタの一覧である。この表は、バージョン 1.0 のピクセル シェーダに適用される。

名前 | 数 | I/O 許可 | 命令あたりの使用可能数
an | 1 スカラー | 書き込み/使用専用 | バージョン 1.0 では 0。バージョン 1.1 では 1。
c[n] | 96 ベクトル | 読み取り専用 | 1
rn | 12 ベクトル | 読み書き可能 | 3
vn | 16 ベクトル | 読み取り専用 | 1


an

これらはアドレス レジスタである。これらのレジスタは、Microsoft® DirectX® 8.0 の頂点シェーダ バージョン 1.0 では使用できず、バージョン 1.1 では単一のレジスタのみ使用できる。a0.x と表されるアドレス レジスタは、定数レジスタ ファイルに対する相対アドレス指定における符号付き整数オフセットとして使用できる。

c[a0.x + n]

有効範囲外からの読み取りに対しては、(0.0, 0.0, 0.0, 0.0) が返る。アドレス レジスタは、mov 命令に対してのみデスティネーションになることができる。頂点シェーダは、アドレス レジスタの値を読み取ることはできず、定数レジスタ ファイルの相対アドレス指定で使用することだけができる。サポートされている定数レジスタの範囲の外側のアドレスが指定されている場合、それによる読み取りからは予測不可能な結果が返る。

アドレス レジスタを使用するバージョン 1.0 の頂点シェーダでは、頂点シェーダを作成する Microsoft Direct3D® API の呼び出しが失敗する。バージョン 1.1 の頂点シェーダも、アドレス レジスタを設定せずに使用を試みると失敗する。


c[n]

これらは定数レジスタである。定数レジスタ ファイルを構成するのは、最低 96 個の 4 成分浮動小数点値ベクトルである。定数レジスタは、絶対位置または相対位置で指定できる。

    c[n]            ; 絶対位置
    c[a0.x + n]     ; 相対位置

したがって、定数レジスタは、絶対アドレスを使って読み取ることも、アドレス レジスタを介して相対的にアドレス指定することもできる。レジスタの範囲外から読み取りを行うと、(0.0, 0.0, 0.0, 0.0) が返る。

頂点シェーダから見ると、定数レジスタ ファイルは読み取り専用である。1 回の命令でアクセスできる定数レジスタは 1 つだけである。ただし、その命令に含まれる各ソースは読み取ったベクトルを個別に入れ換えたり正負を反転したりできる。

D3DCAPS8 の MaxVertexShaderConst メンバは、使用可能な定数レジスタの個数を示す。Microsoft® DirectX® 8.0 のシェーダは、少なくとも 96 個の定数をサポートする。

定数レジスタ ファイルのデータは、頂点シェーダの定数レジスタを設定する Microsoft Direct3D® API 関数を呼び出すとロードされる。代わりに、シェーダを作成するときに、Direct3DDevice8.SetVertexShader の呼び出しによって、Visual Basic アプリケーションでロードする定数を指定できる。


rn

これらはテンポラリ レジスタである。テンポラリ レジスタは、12 個の4D 浮動小数点値ベクトルにグループ化されている。各テンポラリ レジスタに対しては、1 回の書き込みアクセスと 3 回の読み取りアクセスを同時に行うことができる。したがって、1 つの命令は、入力ソース オペランドのセットとしてテンポラリ レジスタを 3 つまで使うことができる。

頂点シェーダによる前回の呼び出し後に残っているテンポラリ レジスタの中の値を使うことはできない。書き込みが行われる前のテンポラリ レジスタから頂点シェーダが読み込みを行うと、その頂点シェーダを作成する Microsoft® Direct3D® API の呼び出しは失敗する。


vn

これらは頂点入力レジスタである。1 つ以上の入力頂点ストリームからの各頂点は、頂点シェーダが実行される前に、頂点入力レジスタにロードされる。頂点入力レジスタは、16 個の 4 成分浮動小数点値ベクトルで構成されているレジスタ ファイルで、v0 から v15 と示される。これらのレジスタは読み取り専用である。

1 回の命令でアクセスできる頂点入力レジスタは 1 つだけである。ただし、その命令に含まれる各ソースは読み取ったベクトルを個別に入れ換えたり、正負を反転させたりできる。

頂点シェーダを作成するために Microsoft® Direct3D® API 呼び出しに渡される宣言では、ソース頂点ストリームと頂点入力レジスタの間のマッピングが定義されている。固定機能パイプラインの場合、入力レジスタは次の表に示されている固定マッピングを持つ。

ベクトル コンポーネント | レジスタ
位置座標 | 0
ブレンドの重み | 1
ブレンド識別子 | 2
法線 | 3
ポイント サイズ | 4
ディフューズ | 5
スペキュラ | 6
テクスチャ座標 | 7
テクスチャ座標 1 | 8
テクスチャ座標 2 | 9
テクスチャ座標 3 | 10
テクスチャ座標 4 | 11
テクスチャ座標 5 | 12
テクスチャ座標 6 | 13
テクスチャ座標 7 | 14
位置座標 2 | 15
法線 2 | 16


出力レジスタ

出力レジスタは、ラスタライザへの入力と定義される。生成されたデータは出力レジスタ ファイルに書き込まれるが、これは書き込み専用のアクセスである。

出力レジスタはラスタ シェーダのレジスタ モデルによって定義されており、次の最低個数をサポートしなければならない。

名前 | I/O 許可 | 数
oDn | 書き込み専用 | 2 つの 4D ベクトル
oFog | 書き込み専用 | 1 スカラー フロート
oPos | 書き込み専用 | 4D ベクトル 1 個
oPts | 書き込み専用 | 1 スカラー フロート
oTn | 書き込み専用 | 4 つの 4D ベクトル

示されていないデスティネーション レジスタへの書き込み処理は無視される。

レジスタ名の前に付いている小文字の o は、出力レジスタが書き込み専用であることを示している。

Microsoft® DirectX® 6.0 または 7.0 のピクセル処理モデルのみをサポートしている実装環境、つまりピクセル シェーダのない実装環境で頂点シェーダを使うときは、次の出力レジスタを利用できる。

名前 | I/0 許可 | 数 | 説明
oDn | 書き込み専用 | 2 ベクトル | 出力カラー データ。ディフューズ色およびスペキュラ色のために必要。
oPos | 書き込み専用 | 1 ベクトル | 出力座標。クリッピングのために必要。
oTn | 書き込み専用 | 2 ベクトル | 出力テクスチャ座標。テクスチャ ブレンディング ステージに同時にバインドできるテクスチャの最大数のために必要。


oDn

出力データ レジスタ。頂点カラー データを出力するために使用される。具体的には、補間されてピクセル シェーダに直接転送される出力データ レジスタの配列である。通常、これらのレジスタは色の処理に使用される。


oFog

出力フォグ値レジスタ。この値は、補間された後フォグ テーブルに転送されるフォグ係数である。フォグのスカラー x 要素だけが使われる。


oPos

出力位置レジスタ。この値は、同次クリッピング空間内の位置座標である。この値は、頂点シェーダが書き込まなければならない。


oPts

出力位置座標サイズ レジスタ。ポイント サイズのスカラー x 要素だけが使われる。


oTn

出力テクスチャ座標レジスタ。具体的には、補間されて、ピクセル シェーダに送られるサンプリング ステージの転送データによってテクスチャ座標として使用される出力データ レジスタの配列である。


命令

ここでは、Direct3DX 頂点シェーダ アセンブラが実装する命令についてのリファレンス情報を記述する。説明するトピックは、次のとおりである。

  • 一般命令
  • バージョンおよび定数定義命令
  • マクロ命令
  • 修飾子

頂点シェーダ プログラムは 128 個までの命令で構成することができ、命令は最大で 3 つの入力引数 (ソース レジスタ オペランド) を持つことができる。


一般命令

Direct3DX 頂点シェーダ アセンブラでは、次の一般的な命令がサポートされている。

add | 加算
dp3 | 3 要素の内積
dp4 | 4 要素の内積
dst | 距離ベクトル
expp | 指数 10 ビット精度
lit | ライティング係数
logp | 対数 10 ビット精度
mad | 乗算と加算
max | 最大
min | 最小
mov | 移動
mul | 乗算
rcp | 逆数
rsq | 逆数平方根
sge | 以上
slt | 未満
sub | 減算

各ソース オペランドは、ある要素を全要素にコピーしたり複製など、読み取り時に自由に入れ換えできる。各ソース オペランドは正負を反転できる。

デスティネーション レジスタへの書き込みには、個々の要素のマスキングを含めることができる。つまり、特定の成分 (x、y、z、または w) だけが更新される。書き込み時の入れ換えや正負の反転はサポートされていない。したがって、出力マスクは、x、y、z、そして w の順序でなければならない。

ソフトウェア エミュレーション フロントエンドは、出力レジスタ書き込みでのマスクを使って、出力頂点の中でシェーダが変更した部分を検出し、それに従って、ラスタ化のみの使用のためにハードウェアに送信するための、出力の柔軟な頂点フォーマット (FVF) を計算する。

ピクセル シェーダ言語とは異なり、頂点シェーダ言語では線形補間ブレンディング命令はサポートされておらず、dp3 演算子は自動的に負の結果を 0.0 に制限しないことに注意すること。

参照

マクロ命令


add

ソースを加算する。

add   vDest, vSrc0, vSrc1

レジスタ

vDest
処理の結果を保持するデスティネーション レジスタ。
vSrc0
入力引数を指定するソース レジスタ。
vSrc1
入力引数を指定するソース レジスタ。

処理

次のコードは、add 命令によって実行される処理とデスティネーションへの結果の書き込みを示している。

    SetDestReg();
    SetSrcReg(0);
    SetSrcReg(1);

    m_TmpReg.x = m_Source[0].x + m_Source[1].x;
    m_TmpReg.y = m_Source[0].y + m_Source[1].y;
    m_TmpReg.z = m_Source[0].z + m_Source[1].z;
    m_TmpReg.w = m_Source[0].w + m_Source[1].w;

    WriteResult();

注意

次の例は、add 命令の使い方を示している。

add r0, v0,c2
add r1.xyz, r0.xyz, v1.xyz


dp3

ソースの 3 要素による内積を計算する。

dp3   vDest, vSrc0, vSrc1

レジスタ

vDest
処理の結果を保持するデスティネーション レジスタ。
vSrc0
入力引数を指定するソース レジスタ。
vSrc1
入力引数を指定するソース レジスタ。

処理

次のコードは、dp3 命令によって実行される処理とデスティネーションへの結果の書き込みを示している。

    SetDestReg();
    SetSrcReg(0);
    SetSrcReg(1);

    m_TmpReg.x =
    m_TmpReg.y =
    m_TmpReg.z =
    m_TmpReg.w = m_Source[0].x * m_Source[1].x +
                 m_Source[0].y * m_Source[1].y +
                 m_Source[0].z * m_Source[1].z;

    WriteResult();

注意

次の例は、dp3 命令の使い方を示している。

dp3 r2, r0, r1
dp3 r2.x, r0, r1


dp4

ソースの 4 要素による内積を計算する。

dp4   vDest, vSrc0, vSrc1

レジスタ

vDest
処理の結果を保持するデスティネーション レジスタ。
vSrc0
入力引数を指定するソース レジスタ。
vSrc1
入力引数を指定するソース レジスタ。

処理

次のコードは、dp4 命令によって実行される処理とデスティネーションへの結果の書き込みを示している。

    SetDestReg();
    SetSrcReg(0);
    SetSrcReg(1);

    m_TmpReg.x =
    m_TmpReg.y =
    m_TmpReg.z =
    m_TmpReg.w = m_Source[0].x * m_Source[1].x +
                 m_Source[0].y * m_Source[1].y +
                 m_Source[0].z * m_Source[1].z +
                 m_Source[0].w * m_Source[1].w;

    WriteResult();

注意

次の例は、dp4 命令の使い方を示している。

dp4 r2, r0, r1
dp4 r2.w, r0, r1


dst

距離関連のデータを計算する。

dst   vDest, vSrc0, vSrc1

レジスタ

vDest
処理の結果を保持するデスティネーション レジスタ。
vSrc0
入力引数を指定するソース レジスタ。
vSrc1
入力引数を指定するソース レジスタ。

処理

次のコードは、dst 命令によって実行される処理とデスティネーションへの結果の書き込みを示している。

    SetDestReg();
    SetSrcReg(0);
    SetSrcReg(1);

    m_TmpReg.x = 1;
    m_TmpReg.y = m_Source[0].y * m_Source[1].y;
    m_TmpReg.z = m_Source[0].z;
    m_TmpReg.w = m_Source[1].w;

    WriteResult();

注意

第 1 のソース オペランドはベクトル (無視, d*d, d*d, 無視) と見なされて、第 2 のソース オペランドはベクトル (無視, 1/d, 無視, 1/d) と見なされる。デスティネーションは、結果のベクトル (1, d, d*d, 1/d) である。

次の例は、dst 命令の使い方を示している。

dst r4, r0, r1


expp

指数 2x の部分サポートを提供する。

expp   vDest, vSrc0

レジスタ

vDest
処理の結果を保持するデスティネーション レジスタ。
vSrc0
入力引数を指定するソース レジスタ。

処理

次のコードは、expp 命令によって実行される処理とデスティネーションへの結果の書き込みを示している。

    SetDestReg();
    SetSrcReg(0);

    float w = m_Source[0].w;
    float v = (float)floor(m_Source[0].w);

    m_TmpReg.x = (float)pow(2, v);
    m_TmpReg.y = w - v;
    // 低精度指数
    float tmp = (float)pow(2, w);
    DWORD tmpd = *(DWORD*)&tmp & 0xffffff00;
    m_TmpReg.z = *(float*)&tmpd;
    m_TmpReg.w = 1;

    WriteResult();

注意

指数に負の数を指定した場合、expp 命令は不定の結果を生成する。

この命令は、2 を底とする指数の部分精度を計算する。vDest.z には近似解が生成されて、より正確な値は vDest.x*function(vDest.y) で求めることができる。function は、限られた範囲 (0.0 <= vDest.y < 1.0) の 2*vDest.y に対してユーザーが使用する近似である。

この命令ではスカラー ソースを使用し、vDest.z の評価には低精度計算が使用できる。ただし、近似エラーは、絶対エラー (10 ビット精度) の 1/(211) より小さく、0.0 <= t.y < 1.0 の範囲内になければならない。また、expp から返る w は 1.0 である。

次の例は、expp 命令の使い方を示している。

expp r5, r0


lit

ライティングの部分サポートを提供する。

lit   vDest, vSrc0

レジスタ

vDest
処理の結果を保持するデスティネーション レジスタ。
vSrc0
入力引数を指定するソース レジスタ。

処理

次のコードは、lit 命令によって実行される処理とデスティネーションへの結果の書き込みを示している。

    SetDestReg();
    SetSrcReg(0);

    m_TmpReg.x = 1;
    m_TmpReg.y = 0;
    m_TmpReg.z = 0;
    m_TmpReg.w = 1;
    float power = m_Source[0].w;
    const float MAXPOWER = 127.9961f;
    if (power < -MAXPOWER)
        power = -MAXPOWER;          // 8.8 固定小数点フォーマットに適合。
    else
    if (power > MAXPOWER)
        power = -MAXPOWER;          // 8.8 固定小数点フォーマットに適合。

    if (m_Source[0].x > 0)
    {
        m_TmpReg.y = m_Source[0].x;
        if (m_Source[0].y > 0)
        {
            // 許容される近似は EXP(power * LOG(m_Source[0].y)) である。
            m_TmpReg.z = (float)(pow(m_Source[0].y, power));
        }
    }

    WriteResult();

注意

指数に負の数を指定した場合、lit 命令は不定の結果を生成する。

この命令は、2 つの内積と 1 つの累乗からライティング係数を計算する。ソースのベクトルには、次の疑似コードに示すような値が含まれているものと想定される。

vSrc0.x = N*L        ; 法線とライト ベクトルとの内積
vSrc0.y = N*H        ; 法線と半ベクトルとの内積
vSrc0.z = ignored    ; この値は無視される
vSrc0.w = power      ; 累乗、この値は -128.0 から 128.0 の範囲でなければならない

vDest.z の評価には低精度計算が使用できる。実装では、累乗引数で少なくとも 8 つの小数ビットをサポートする必要がある。内積は正規化されたベクトルで計算されて、クランプの制限は -128 から 128 である。

エラーは logp と expp の組み合わせに対応していなければならず、つまり 8 ビットの色成分に対して最下位ビット (LSB) 約 1 つである。

次の例は、lit 命令の使い方を示している。

lit r0, r1


logp

log2(x) の部分サポートを提供する。

logp   vDest, vSrc0

レジスタ

vDest
処理の結果を保持するデスティネーション レジスタ。
vSrc0
入力引数を指定するソース レジスタ。

処理

次のコードは、logp 命令によって実行される処理とデスティネーションへの結果の書き込みを示している。

    SetDestReg();
    SetSrcReg(0);

    float v = ABSF(m_Source[0].w);
    if (v != 0)
    {
        m_TmpReg.x = m_TmpReg.y = m_TmpReg.z = m_TmpReg.w =
            (float)(log(v)/log(2));
    }
    else
    {
        m_TmpReg.x = m_TmpReg.y = m_TmpReg.z = m_TmpReg.w = MINUS_INFINITY();
    }

    WriteResult();

注意

この命令は、2 を底とする対数の部分精度を計算する。vDest.z には近似解が生成されて、より正確な値は vDest.x + function(vDest.y) で求めることができる。function は、限られた範囲 (1.0 <= vDest.y < 2.0) の log2(vDest.y) に対してユーザーが使用する近似である。

logp 命令では、符号ビットは無視されるスカラー ソースを使用し、vDest.z の評価には低精度計算が使用できる。近似エラーは、絶対エラー (10 ビット精度) の 1/(211) より小さく、1.0 <= t.y < 2.0 の範囲内になければならない。ソース引数が 0 の場合は、結果のベクトル (-infinity, 0.0, -infinity, 1.0) が生成される。

次の例は、logp 命令の使い方を示している。

logp r0,r1


mad

ソースを乗算および加算する。

mad   vDest, vSrc0, vSrc1, vSrc2

レジスタ

vDest
処理の結果を保持するデスティネーション レジスタ。
vSrc0
入力引数を指定するソース レジスタ。
vSrc1
入力引数を指定するソース レジスタ。
vSrc2
入力引数を指定するソース レジスタ。

処理

次のコードは、mad 命令によって実行される処理とデスティネーションへの結果の書き込みを示している。

    SetDestReg();
    SetSrcReg(0);
    SetSrcReg(1);
    SetSrcReg(2);

    m_TmpReg.x = m_Source[0].x * m_Source[1].x + m_Source[2].x;
    m_TmpReg.y = m_Source[0].y * m_Source[1].y + m_Source[2].y;
    m_TmpReg.z = m_Source[0].z * m_Source[1].z + m_Source[2].z;
    m_TmpReg.w = m_Source[0].w * m_Source[1].w + m_Source[2].w;

    WriteResult();

注意

次の例は、mad 命令の使い方を示している。

mad r0,r1,r2,v3


max

ソースの最大値を計算する。

max   vDest, vSrc0, vSrc1

レジスタ

vDest
処理の結果を保持するデスティネーション レジスタ。
vSrc0
入力引数を指定するソース レジスタ。
vSrc1
入力引数を指定するソース レジスタ。

処理

次の疑似コードは、max 命令によって実行される処理とデスティネーションへの結果の書き込みを示している。

    SetDestReg();
    SetSrcReg(0);
    SetSrcReg(1);

    m_TmpReg.x=(m_Source[0].x >= m_Source[1].x) ? m_Source[0].x : m_Source[1].x;
    m_TmpReg.y=(m_Source[0].y >= m_Source[1].y) ? m_Source[0].y : m_Source[1].y;
    m_TmpReg.z=(m_Source[0].z >= m_Source[1].z) ? m_Source[0].z : m_Source[1].z;
    m_TmpReg.w=(m_Source[0].w >= m_Source[1].w) ? m_Source[0].w : m_Source[1].w;

    WriteResult();

注意

次の例は、max 命令の使い方を示している。

max r2, r3, r4


min

ソースの最小値を計算する。

min   vDest, vSrc0, vSrc1

レジスタ

vDest
処理の結果を保持するデスティネーション レジスタ。
vSrc0
入力引数を指定するソース レジスタ。
vSrc1
入力引数を指定するソース レジスタ。

処理

次のコードは、min 命令によって実行される処理とデスティネーションへの結果の書き込みを示している。

    SetDestReg();
    SetSrcReg(0);
    SetSrcReg(1);

    m_TmpReg.x=(m_Source[0].x < m_Source[1].x) ? m_Source[0].x : m_Source[1].x;
    m_TmpReg.y=(m_Source[0].y < m_Source[1].y) ? m_Source[0].y : m_Source[1].y;
    m_TmpReg.z=(m_Source[0].z < m_Source[1].z) ? m_Source[0].z : m_Source[1].z;
    m_TmpReg.w=(m_Source[0].w < m_Source[1].w) ? m_Source[0].w : m_Source[1].w;

    WriteResult();

注意

次の例は、min 命令の使い方を示している。

min   r2, r3, r4


mov

ソースの内容をデスティネーションに移動する。

mov   vDest, vSrc0

レジスタ

vDest
処理の結果を保持するデスティネーション レジスタ。
vSrc0
入力引数を指定するソース レジスタ。

処理

次のコードは、mov 命令によって実行される処理とデスティネーションへの結果の書き込みを示している。

    SetDestReg();
    SetSrcReg(0);

    if( m_pDest == m_reg.m_a )
    {
        float p = (float)floor(m_Source[0].x);
        *(int*)&m_pDest->x = FTOI(p);
    }
    else
    {
        m_TmpReg = m_Source[0];
        WriteResult();
    }

注意

次の例は、mov 命令の使い方を示している。

mov r1, v2
mov r1.xy, r2.zw


mul

ソースを乗算してデスティネーションに格納する。

mul   vDest, vSrc0, vSrc1

レジスタ

vDest
処理の結果を保持するデスティネーション レジスタ。
vSrc0
入力引数を指定するソース レジスタ。
vSrc1
入力引数を指定するソース レジスタ。

処理

次のコードは、mul 命令によって実行される処理とデスティネーションへの結果の書き込みを示している。

    SetDestReg();
    SetSrcReg(0);
    SetSrcReg(1);

    m_TmpReg.x = m_Source[0].x * m_Source[1].x;
    m_TmpReg.y = m_Source[0].y * m_Source[1].y;
    m_TmpReg.z = m_Source[0].z * m_Source[1].z;
    m_TmpReg.w = m_Source[0].w * m_Source[1].w;

    WriteResult();

注意

次の例は、mul 命令の使い方を示している。

mul r4, v0, r1


rcp

ソース スカラーの逆数を計算する。

rcp   vDest, vSrc0

レジスタ

vDest
処理の結果を保持するデスティネーション レジスタ。
vSrc0
入力引数を指定するソース レジスタ。

処理

次のコードは、rcp 命令によって実行される処理とデスティネーションへの結果の書き込みを示している。

    SetDestReg();
    SetSrcReg(0);

    if( m_Source[0].w == 1.0f )
    {
        // 正確に 1.0 でなければならない。
        m_TmpReg.x = m_TmpReg.y = m_TmpReg.z = m_TmpReg.w = 1.0f;
    }
    else if( m_Source[0].w == 0 )
    {
        m_TmpReg.x = m_TmpReg.y = m_TmpReg.z = m_TmpReg.w = PLUS_INFINITY();
    }
    else
    {
        m_TmpReg.x = m_TmpReg.y = m_TmpReg.z = m_TmpReg.w = 1.0f/m_Source[0].w;
    }

    WriteResult();

注意

ソースに添字がない場合は、x 要素が使われる。入力が 1.0 の場合は、出力も 1.0 にならなければならない。

(1.0, 2.0) の範囲を超えたエラーの精度は少なくとも 1.0/(222) 絶対値である。これは、通常の実装では仮数と指数が分離されるためである。0.0 のソースは無限大である。

次の例は、rcp 命令の使い方を示している。

rcp r1, r2
rcp r1, r2.y


rsq

ソース スカラーの逆数の平方根を計算する。

rsq   vDest, vSrc0

レジスタ

vDest
処理の結果を保持するデスティネーション レジスタ。
vSrc0
入力引数を指定するソース レジスタ。

処理

次のコードは、rsq 命令によって実行される処理とデスティネーションへの結果の書き込みを示している。

    SetDestReg();
    SetSrcReg(0);

    float v = ABSF(m_Source[0].w);
    if( v == 1.0f )
    {
        m_TmpReg.x = m_TmpReg.y = m_TmpReg.z = m_TmpReg.w = 1.0f;
    }
    else if( v == 0 )
    {
        m_TmpReg.x = m_TmpReg.y = m_TmpReg.z = m_TmpReg.w = PLUS_INFINITY();
    }
    else
    {
        v = (float)(1.0f / sqrt(v));
        m_TmpReg.x = m_TmpReg.y = m_TmpReg.z = m_TmpReg.w = v;
    }

    WriteResult();

注意

ソースに添字がない場合は、x 要素が使われる。入力が 1.0 の場合は、出力も 1.0 にならなければならない。

絶対値は処理の前に取得される。つまり、符号ビットは無視される。

(1.0, 4.0) の範囲を超えたエラーの精度は少なくとも 1.0/(222) 絶対値である。これは、通常の実装では仮数と指数が分離されるためである。0.0 のソースは無限大である。

次の例は、rsq 命令の使い方を示している。

rsq r1, r2
rsq r1, r2.y


sge

第 1 ソース オペランドの値が第 2 ソース オペランドの値以上の場合は、デスティネーションに 1.0 を設定する。それ以外の場合は、デスティネーションに 0.0 を設定する。

sge   vDest, vSrc0, vSrc1

レジスタ

vDest
処理の結果を保持するデスティネーション レジスタ。
vSrc0
入力引数を指定するソース レジスタ。
vSrc1
入力引数を指定するソース レジスタ。

処理

次のコードは、sge 命令によって実行される処理とデスティネーションへの結果の書き込みを示している。

    SetDestReg();
    SetSrcReg(0);
    SetSrcReg(1);

    m_TmpReg.x = (m_Source[0].x >= m_Source[1].x) ? 1.0f : 0.0f;
    m_TmpReg.y = (m_Source[0].y >= m_Source[1].y) ? 1.0f : 0.0f;
    m_TmpReg.z = (m_Source[0].z >= m_Source[1].z) ? 1.0f : 0.0f;
    m_TmpReg.w = (m_Source[0].w >= m_Source[1].w) ? 1.0f : 0.0f;

    WriteResult();

注意

次の例は、sge 命令の使い方を示している。

sge   r1, r2, v1


slt

第 1 ソース オペランドの値が第 2 ソース オペランドの値未満の場合は、デスティネーションに 1.0 を設定する。それ以外の場合は、デスティネーションに 0.0 を設定する。

slt   vDest, vSrc0, vSrc1

レジスタ

vDest
処理の結果を保持するデスティネーション レジスタ。
vSrc0
入力引数を指定するソース レジスタ。
vSrc1
入力引数を指定するソース レジスタ。

処理

次のコードは、slt 命令によって実行される処理とデスティネーションへの結果の書き込みを示している。

    SetDestReg();
    SetSrcReg(0);
    SetSrcReg(1);

    m_TmpReg.x = (m_Source[0].x < m_Source[1].x) ? 1.0f : 0.0f;
    m_TmpReg.y = (m_Source[0].y < m_Source[1].y) ? 1.0f : 0.0f;
    m_TmpReg.z = (m_Source[0].z < m_Source[1].z) ? 1.0f : 0.0f;
    m_TmpReg.w = (m_Source[0].w < m_Source[1].w) ? 1.0f : 0.0f;

    WriteResult();

注意

次の例は、slt 命令の使い方を示している。

slt   r1, r2, v1


sub

ソースを減算する。

sub   tDest, tSrc0, tSrc1

レジスタ

tDest
処理の結果を保持するデスティネーション レジスタ。
tSrc0
入力引数を指定するソース レジスタ。
tSrc1
入力引数を指定するソース レジスタ。

注意

この命令は、次の公式に基づいて減算を行う。

tDest = tSrc0 - tSrc1

次の例は、この命令の使い方を示している。

sub   r2, v2, r2    ; difference


バージョンおよび定数定義命令

Direct3DX 頂点シェーダ アセンブラには、シェーダのタイプおよびバージョンを識別したり、頂点シェーダで使用する定数を定義するための命令が用意されている。

def | 定数を定義する
vs | バージョンおよびタイプ

バージョン命令は、各シェーダの先頭にある必要がある。

定数定義命令は、バージョン命令の実行後、ほかのすべての命令よりも前に実行しなければならないことに注意すること。


def

頂点シェーダで使用する定数を定義するためのメソッドを提供する。

def   vDest, fVal0, fVal1, fVal2, fVal3

レジスタ

vDest
処理の結果を保持するデスティネーション レジスタ。
fVal0
入力引数を指定するソース レジスタ。
fVal1
入力引数を指定するソース レジスタ。
fVal2
入力引数を指定するソース レジスタ。
fVal3
入力引数を指定するソース レジスタ。

注意

次の例は、def 命令の使い方を示している。

def c0, 0.0f, 0.0f, 0.0f, 1.0f
def c8, 1.0f, 2.0f, 3.0f, 4.0f

これらの定数は、シェーダの作成時に宣言に含まれる宣言の一部として返される。


vs

シェーダ コードのタイプおよびバージョンを指定するためのメソッドを提供する。

vs.mainVer.subVer

レジスタ

mainVer
頂点シェーダのメイン バージョン番号。
subVer
頂点シェーダのサブ バージョン番号。

注意

次の例は、vs 命令の使い方を示している。

vs.1.0  ; 頂点シェーダ バージョン 1.0

この命令は、すべての頂点シェーダの先頭にある必要がある。


マクロ命令

Direct3DX 頂点シェーダ アセンブラでは、共通の単純な処理を実行する際のアプリケーションの便宜のために、マクロ命令が提供されている。これらのマクロは、ドライバによって、いくつかの標準的な頂点シェーダ命令に拡張されている。詳細については、各マクロ命令のリファレンス トピックを参照すること。

exp | 2 を底とする指数の完全精度
frc | 小数部
log | 2 を底とする対数の完全精度
m3x2 | 3 × 2 ベクトル行列の乗算
m3x3 | 3 × 3 ベクトル行列の乗算
m3x4 | 3 × 4 ベクトル行列の乗算
m4x3 | 4 × 3 ベクトル行列の乗算
m4x4 | 4 × 4 ベクトル行列の乗算

命令の数の上限である 128 を超えるかどうかを判断できるようにするため、マクロ命令は、列記されている実際の命令の数を超えないことが保証されている。

マクロ命令は実際の命令と同じ方法で実装環境に渡されるので、実装環境は自由にマクロ命令を最適化できる。したがって、必要なタイミング サイクル カウントについてはいかなる想定もできない。

参照

一般命令


exp

最低 1/220 の完全精度の指数 2x を提供する。

exp   vDest, vSrc0

レジスタ

vDest
処理の結果を保持するデスティネーション レジスタ。
vSrc0
入力引数を指定するソース レジスタ。

処理

    SetDestReg();
    SetSrcReg(0);

    float v = m_Source[0].w;

    m_TmpReg.x = m_TmpReg.y = m_TmpReg.z = m_TmpReg.w = (float)pow(2, v);

    WriteResult();

展開

このマクロは 12 の命令スロットを使用する。

注意

これはスカラー演算であり、その入力を .w チャネルから取る。このチャネルは指定する必要がある。この演算は、常に 4 つのすべてのチャネルに結果を複製する。


frc

各入力要素の小数部分を返す。

frc   vDest, vSrc0

レジスタ

vDest
処理の結果を保持するデスティネーション レジスタ。
vSrc0
入力引数を指定するソース レジスタ。

処理

    SetDestReg();
    SetSrcReg(0);

    m_TmpReg.x = m_Source[0].x - (float)floor(m_Source[0].x);
    m_TmpReg.y = m_Source[0].y - (float)floor(m_Source[0].y);
    m_TmpReg.z = m_Source[0].z - (float)floor(m_Source[0].z);
    m_TmpReg.w = m_Source[0].w - (float)floor(m_Source[0].w);

    WriteResult();

展開

このマクロは 3 つの命令スロットを使用する。

注意

結果の各要素は、0.0 から 1.0 の範囲である。

このマクロは x および y 要素を記述するのみである。


log

最低 1/220 の完全浮動小数点精度で log2(x) のサポートを提供する。

log   vDest, vSrc0

レジスタ

vDest
処理の結果を保持するデスティネーション レジスタ。
vSrc0
入力引数を指定するソース レジスタ。

処理

    SetDestReg();
    SetSrcReg(0);

    float v = ABSF(m_Source[0].w);
    if (v != 0)
    {
        m_TmpReg.x = m_TmpReg.y = m_TmpReg.z = m_TmpReg.w =
            (float)(log(v)/log(2));
    }
    else
    {
        m_TmpReg.x = m_TmpReg.y = m_TmpReg.z = m_TmpReg.w = minUS_INFINITY();
    }

    WriteResult();

展開

このマクロは 12 の命令スロットを使用する。

注意

この命令では符号ビットを無視したスカラー ソース .w が受け入れられる。結果は 4 つのすべてのチャネルに複製される。

入力指数の範囲は、-128 から 128 まででなければならない。近似エラーは、絶対エラーの 1/220 より小さく、1.0 <= t.y < 2.0 の範囲内になければならない。ソースが 0 の場合は、(-infinity,-infinity,-infinity,-infinity) が生成される。


m3x2

入力ベクトルと 3 × 2 行列の積を計算する。

m3x2   rDest, vSrc0, mSrc1

レジスタ

rDest
処理の結果を保持するデスティネーション レジスタ。
vSrc0
入力引数を指定するソース レジスタ。
mSrc1
入力引数を指定するソース レジスタ。

処理

    SetDestReg();
    SetSrcReg(0);
    SetSrcReg(1, 2);
    m_TmpReg.x = m_Source[0].x * m_Source[1].x +
                 m_Source[0].y * m_Source[1].y +
                 m_Source[0].z * m_Source[1].z;
    m_TmpReg.y = m_Source[0].x * m_Source[2].x +
                 m_Source[0].y * m_Source[2].y +
                 m_Source[0].z * m_Source[2].z;

    WriteResult();

展開

次の例は m3x2 命令の使い方を示している。

m3x2   r5, v0, c[3]

内容

dp3   r5.x, v0, c[3]
dp3   r5.y, v0, c[4]

したがって、このマクロ命令は、命令カウントから命令スロットを 2 つ消費する。c[3] および c[4] の最後の w 要素はこの計算においては無視されることに注意する。

注意

入力ベクトルは vSrc0 であり、入力の 3 × 2 行列は mSrc1 および同じレジスタ ファイル内の次のレジスタである。2D の結果が生成されて、rDest のほかの要素 (z および w) は変更されないでそのまま残る。

この処理は、一般に、2D トランスフォームに使用される。このマクロ命令は、1 対の内積として実装される。


m3x3

入力ベクトルと 3 × 3 行列の積を計算する。

m3x3   rDest, vSrc0, mSrc1

レジスタ

rDest
処理の結果を保持するデスティネーション レジスタ。
vSrc0
入力引数を指定するソース レジスタ。
mSrc1
入力引数を指定するソース レジスタ。

処理

    SetDestReg();
    SetSrcReg(0);
    SetSrcReg(1, 3);
    m_TmpReg.x = m_Source[0].x * m_Source[1].x +
                 m_Source[0].y * m_Source[1].y +
                 m_Source[0].z * m_Source[1].z;
    m_TmpReg.y = m_Source[0].x * m_Source[2].x +
                 m_Source[0].y * m_Source[2].y +
                 m_Source[0].z * m_Source[2].z;
    m_TmpReg.z = m_Source[0].x * m_Source[3].x +
                 m_Source[0].y * m_Source[3].y +
                 m_Source[0].z * m_Source[3].z;

    WriteResult();

展開

次の例は m3x3 命令の使い方を示している。

m3x3   r5, v0, c[3]

内容

dp3   r5.x, v0, c[3]
dp3   r5.y, v0, c[4]
dp3   r5.z, v0, c[5]

したがって、このマクロ命令は、命令カウントから命令スロットを 3 つ消費する。c[3]、c[4]、および c[5] の最後の w 要素はこの計算においては無視されることに注意すること。

注意

入力ベクトルは vSrc0 であり、入力の 3 × 3 行列は mSrc1 および同じレジスタ ファイル内でこれに続く 2 つのレジスタである。

この処理は、一般に、ライティング計算の際の法線ベクトルのトランスフォームに使用される。このマクロ命令は、一連の内積として実装される。


m3x4

入力ベクトルと 3 × 4 行列の積を計算する。

m3x4   rDest, vSrc0, mSrc1

レジスタ

rDest
処理の結果を保持するデスティネーション レジスタ。
vSrc0
入力引数を指定するソース レジスタ。
mSrc1
入力引数を指定するソース レジスタ。

処理

    SetDestReg();
    SetSrcReg(0);
    SetSrcReg(1, 4);
    m_TmpReg.x = m_Source[0].x * m_Source[1].x +
                 m_Source[0].y * m_Source[1].y +
                 m_Source[0].z * m_Source[1].z;
    m_TmpReg.y = m_Source[0].x * m_Source[2].x +
                 m_Source[0].y * m_Source[2].y +
                 m_Source[0].z * m_Source[2].z;
    m_TmpReg.z = m_Source[0].x * m_Source[3].x +
                 m_Source[0].y * m_Source[3].y +
                 m_Source[0].z * m_Source[3].z;
    m_TmpReg.w = m_Source[0].x * m_Source[4].x +
                 m_Source[0].y * m_Source[4].y +
                 m_Source[0].z * m_Source[4].z;

    WriteResult();

展開

次の例は m3x4 命令の使い方を示している。

m3x4   r5, v[0], c[3]

内容

dp3 r5.x, v[0], c[3]
dp3 r5.y, v[0], c[4]
dp3 r5.z, v[0], c[5]
dp3 r5.w, v[0], c[6]

したがって、このマクロ命令は、命令カウントから命令スロットを 4 つ消費する。c[3]、c[4]、および c[5] の最後の w 要素はこの計算においては無視されることに注意すること。

注意

入力ベクトルは vSrc0 であり、入力の 3 × 4 行列は mSrc1 および同じレジスタ ファイル内でこれに続く 2 つのレジスタである。

この処理は、一般に、射影エフェクトはあるが平行移動は行わない行列による、位置ベクトルのトランスフォームに使用される。このマクロ命令は、一連の内積として実装される。


m4x3

入力ベクトルと 4 × 3 行列の積を計算する。

m4x3   rDest, vSrc0, mSrc1

レジスタ

rDest
処理の結果を保持するデスティネーション レジスタ。
vSrc0
入力引数を指定するソース レジスタ。
mSrc1
入力引数を指定するソース レジスタ。

処理

    SetDestReg();
    SetSrcReg(0);
    SetSrcReg(1, 3);
    m_TmpReg.x = m_Source[0].x * m_Source[1].x +
                 m_Source[0].y * m_Source[1].y +
                 m_Source[0].z * m_Source[1].z +
                 m_Source[0].w * m_Source[1].w;
    m_TmpReg.y = m_Source[0].x * m_Source[2].x +
                 m_Source[0].y * m_Source[2].y +
                 m_Source[0].z * m_Source[2].z +
                 m_Source[0].w * m_Source[2].w;
    m_TmpReg.z = m_Source[0].x * m_Source[3].x +
                 m_Source[0].y * m_Source[3].y +
                 m_Source[0].z * m_Source[3].z +
                 m_Source[0].w * m_Source[3].w;

    WriteResult();

展開

次の例は m4x3 命令の使い方を示している。

m4x3   r5, v[0], c[3]

内容

dp4   r5.x, v[0], c[3]
dp4   r5.y, v[0], c[4]
dp4   r5.z, v[0], c[5]

したがって、このマクロ命令は、命令カウントから命令スロットを 3 つ消費する。入力ベクトルの w の値が 1.0 でない限り、c[3]、c[4]、および c[5] の最後の w 要素はこの計算においては無視されることに注意すること。この w の値が 0.0 の場合は、入力ベクトルの平行移動は行われない。つまり、行列の平行移動要素は適用されない。

注意

入力ベクトルは vSrc0 であり、入力の 4 × 3 行列は mSrc1 および同じレジスタ ファイル内でこれに続く 2 つのレジスタである。

この処理は、一般に、モデル空間のトランスフォームにおいて発生する場合など、射影エフェクトのない行列による位置ベクトルのトランスフォームに使用される。このマクロ命令は、一連の内積として実装される。


m4x4

入力ベクトルと 4 × 4 行列の積を計算する。

m4x4   rDest, vSrc0, mSrc1

レジスタ

rDest
処理の結果を保持するデスティネーション レジスタ。
vSrc0
入力引数を指定するソース レジスタ。
mSrc1
入力引数を指定するソース レジスタ。

処理

   SetDestReg();
    SetSrcReg(0);
    SetSrcReg(1, 4);
    m_TmpReg.x = m_Source[0].x * m_Source[1].x +
                 m_Source[0].y * m_Source[1].y +
                 m_Source[0].z * m_Source[1].z +
                 m_Source[0].w * m_Source[1].w;
    m_TmpReg.y = m_Source[0].x * m_Source[2].x +
                 m_Source[0].y * m_Source[2].y +
                 m_Source[0].z * m_Source[2].z +
                 m_Source[0].w * m_Source[2].w;
    m_TmpReg.z = m_Source[0].x * m_Source[3].x +
                 m_Source[0].y * m_Source[3].y +
                 m_Source[0].z * m_Source[3].z +
                 m_Source[0].w * m_Source[3].w;
    m_TmpReg.w = m_Source[0].x * m_Source[4].x +
                 m_Source[0].y * m_Source[4].y +
                 m_Source[0].z * m_Source[4].z +
                 m_Source[0].w * m_Source[4].w;

    WriteResult();

展開

次の例は m4x4 命令の使い方を示している。

m4x4   r5, v[0], c[3]

内容

dp4   r5.x, v[0], c[3]
dp4   r5.y, v[0], c[4]
dp4   r5.z, v[0], c[5]
dp4   r5.w, v[0], c[6]

したがって、このマクロは、命令カウントから 4 つの命令スロットを使用する。

注意

入力ベクトルは vSrc0 であり、入力の 4 × 4 行列は mSrc1 および同じレジスタ ファイル内でこれに続く 3 つのレジスタである。

この処理は、一般に、射影行列による位置座標のトランスフォームに使われる。このマクロ命令は、一連の内積として実装される。


修飾子

ここでは、Direct3DX 頂点シェーダ アセンブラが実装する成分修飾子についてのリファレンス情報を記述する。

次の表で示すように、成分修飾子 (x は有効なレジスタ、つまり an、c[n]、rn、vn、または出力レジスタのいずれか) は、ベクトル データの個別の成分に適用できる。

成分修飾子 | 説明
r.{x}{y}{z}{w} | デスティネーション マスク
r.[xyzw][xyzw][xyzw][xywz] | ソースの入れ換え
-r | デスティネーションの正負を反転


ピクセル シェーダ アセンブラ リファレンス

ここでは、Direct3DX ピクセル シェーダ アセンブラについてのリファレンス情報を記述する。リファレンス情報は次のカテゴリに分類されている。

  • レジスタ
  • 命令
  • 修飾子
  • 出力書き込みマスク

ピクセル シェーダ アセンブラは、一連のレジスタおよびそのレジスタ上で実行できる処理群で構成されている。処理は、演算子と 1 つ以上の引数 (オペランド) で構成される命令として表現されている。

Microsoft® DirectX® 8.0 では、すべてのサーフェス フォーマットに対して少なくとも 8 ビットの精度を維持するための中間計算が必要である。ステージ内の計算では高精度 (12 ビット) が、テクスチャ ステージ間では 8 ビットに収めることが推奨されている。修正可能な丸めモードや例外はサポートされていない。精度の損失を最小化するために、直近値丸め精度の乗算がサポートされている必要がある。


レジスタ

ここでは、Direct3DX ピクセル シェーダ アセンブラが実装するレジスタについてのリファレンス情報を記述する。

名前 | I/0 許可 | 最小カウント | 命令ごとの最大カウント | ソース
cn | 読み取り専用 | 8 | 2 | API 呼び出し
rn | 読み書き可能 | 2 | 2 | 書き込まれた
tn | 読み書き可能 | 4 | 1 | テクスチャ
vn | 読み取り専用 | 2 | 1 | 頂点カラー

「最小カウント」の列は、Microsoft® DirectX® 8.0 のシェーディング能力を公開するために実装環境がサポートしなければならないレジスタの最小個数を示している。

「命令ごとの最大カウント」の列は、1 つの命令がサポートするレジスタの最大個数を示している。これには、命令に対するソース パラメータの読み取りポートが含まれる。命令のデスティネーション パラメータに制限は適用されない。

各レジスタは 4 要素のベクトルであり、要素の範囲は -1.0 から 1.0 までで、要素ごとの精度は最低 8 ビットである。頂点シェーダ アセンブラとは異なり、ピクセル シェーダ アセンブラは出力レジスタを持たない。ピクセル シェーダは r0 だけを出力する。


cn

これらは定数レジスタである。定数 D3DRS_TEXTUREFACTOR から取得される固定要素レジスタは、Direct3DDevice8.SetPixelShaderConstant メソッドを使ってアプリケーションによってロードされる。

固定要素レジスタは読み取り専用である。ピクセル シェーダ用に少なくとも 8 つの固定要素レジスタが定義されるが、1 つの命令で使用できるのは 2 つまでである。


rn

これらはテンポラリ レジスタである。テンポラリ レジスタは中間結果を格納するために使用できる。テンポラリ レジスタは読み書き可能で、1 つのシェーダ命令で使用できるのは 2 つまでである。デバッグ ランタイムにおけるシェーダの前処理では、前の命令で書き込まれていないテンポラリ レジスタから読み取りを行おうとするシェーダについて、Direct3DDevice8.CreatePixelShader は失敗する。

すべてのピクセル シェーダは最終結果として r0 を書き込む必要があるため、最も単純なデカール ピクセル シェーダは 2 つの命令で構成される。

ps.1.0       // DirectX8 バージョン。
tex   t0
mov   r0, t0


tn

これらはテクスチャ レジスタである。テクスチャ レジスタの最大数は、同時にサポートされるテクスチャの数と同じである。テクスチャ レジスタは、そのステージのテクスチャ ステージ ステートによって定義されるフィルタリング モードを含む、テクスチャ サンプリング ユニットからのテクスチャ カラーを格納することで初期化される。色は、Direct3DDevice8.SetTexture で定義されている対応するテクスチャから取得され、対応するテクスチャ座標でサンプリングされる。

テクスチャ セットを持たないすべてのテクスチャ レジスタは、不透明の黒 (0,0,0,1) としてサンプリングされる。1 つのシェーダ命令で使用できるテクスチャ レジスタは 2 つまでである。テクスチャ レジスタは、テンポラリ レジスタとしても使用できる。具体的には、テクスチャ アドレッシング命令の後で、これらのレジスタは読み書きテンポラリ レジスタとして使用できる。

ほとんどの場合、テクスチャ レジスタは、テクスチャ コマンドのデスティネーションとしてのみ有効である。ただし、テクスチャ レジスタから算術命令を読み取ることができることに注意すること。


vn

これらは頂点カラー レジスタである。入力頂点カラー レジスタには、頂点シェーダから出力されるカラー値のピクセル単位のグーロー補間によって取得されるカラー値が格納される (頂点シェーダはカラー値を頂点ストリームから受け取ることができる)。Microsoft® DirectX® 8.0 に準拠した実装では、少なくとも 2 つの入力カラー レジスタをサポートしなければならない。

入力カラー レジスタは読み取り専用で、1 つの命令ではこれらの色のうち 1 つだけ使用できる。

フラット シェーディングをシミュレートするにはコンスタント カラーの方が効果的である。ただし、シェード モードが D3DSHADE_FLAT のときは、どちらの色の補間も無効になっている。フォグは引き続き補間されなければならないことに注意する必要がある。理想的には、すべての色補間は、テクスチャ座標補間と同じ方法のパースペクティブ補正でなければならない。


命令

Direct3DX コンパイラが認識する、ピクセル シェーダに対する処理は主に 2 つに分類され、ピクセル色およびアルファ ブレンディング処理と、テクスチャ ブレンディング処理がある。アセンブラは、命令を使ってこれらの処理を提供している。ピクセル色およびアルファ ブレンディング処理はカラー データを変更するもので、テクスチャ アドレッシング処理はテクスチャの座標データを操作および処理する。ピクセル シェーダのすべての命令はピクセル単位に実行される。つまり、パイプライン内のほかのピクセルは認識されない。

  • 色およびアルファ ブレンディング命令
  • バージョンおよび定数定義命令
  • テクスチャ アドレッシング命令

ブレンディング処理は、RGB 色とスカラー アルファの個別処理に使用できる。ほとんどの場合、ピクセル ブレンディング (色またはアルファ) 処理は、色命令とアルファ命令の両方を 1 スロットでサポートできる。

準拠した実装では、最低 8 つのブレンディング命令と 4 つのアドレッシング命令のプログラムをサポートしなければならない。

テクスチャ アドレッシング処理はそれぞれ 1 スロットを使用するが、ピクセル ブレンディング (色およびアルファ) 処理は対にして、色命令とアルファ命令の両方を 1 スロットで実行できる。Microsoft® DirectX® 8.0 では、テクスチャ アドレッシング命令はカラー ブレンディング命令より先に実行しなければならない。

テクスチャ アドレス補正処理の構文は、シェーダ プログラム自体に、テクスチャ宣言の形式で含まれている。これらは、ピクセル シェーダ本体で使用するためにテンポラリ レジスタ ファイルにプリロードするときにテクスチャからサンプリングされる色の値に対して、どのようにアドレス補正処理を適用するかを制御する。


色およびアルファ ブレンディング命令

ここでは、Direct3DX ピクセル シェーダ アセンブラが実装する色およびアルファ ブレンディング命令についてのリファレンス情報を記述する。

次の表は、色およびアルファ ブレンディング命令の一覧である。これらの処理はすべてコンポーネント単位で実行される。

命令 | 説明
add | 加算
cnd | 条件
dp3 | 3 要素ベクトルの内積
lrp | 線形補間ブレンディング
mad | 乗算と加算
mov | コピー元からコピー先へのコピー
mul | 乗算
sub | ソース オペランドの 2 色の差をロードする


add

ソース オペランドの 2 つの色の合計をロードする。

add   tDest, tSrc0, tSrc1

レジスタ

tDest
処理の結果を保持するデスティネーション レジスタ。
tSrc0
入力引数を指定するソース レジスタ。
tSrc1
入力引数を指定するソース レジスタ。

注意

次の例は、この命令の使い方を示している。

add d, s1, s2    ; sum d = s1 + s2


cnd

r0.a の値を 0.5 と比較する条件演算を実行する。

cnd   tDest, tSrc0, tSrc1, tSrc2

レジスタ

tDest
処理の結果を保持するデスティネーション レジスタ。
tSrc0
入力引数を指定するソース レジスタ。
tSrc1
入力引数を指定するソース レジスタ。
tSrc2
入力引数を指定するソース レジスタ。

注意

この命令は、r0.a の値と 0.5 を比較するためにのみ使用できる。アルファ (r0.a) が 0.5 よりも大きい場合、最初のソースが結果として返される。それ以外の場合は、2 番目のソースが返される。

次の例は、この命令の使い方を示している。

cnd d, r0.a, s1, s2    ; d = ( r0.a >0.5 ? s1 : s2 )

a - (b - 0.5) = a - b + 0.5 なので、2 つの値を比較するには、次のピクセル シェーダ コードを使用できる。

sub r0, v0,   v1_bias
cnd r0, r0.a, c0, c1

前に説明したように、最初のソース引数に配置できる値は r0.a だけであり、比較値は "0.5 よりも大きく" なければならない。


dp3

ソース オペランド レジスタの 2 色の 3 要素ベクトル内積をロードする。

dp3   tDest, tSrc0, tSrc1

レジスタ

tDest
処理の結果を保持するデスティネーション レジスタ。
tSrc0
入力引数を指定するソース レジスタ。
tSrc1
入力引数を指定するソース レジスタ。

注意

この命令はスカラーの結果を生成するが、それを指定されたすべての出力チャネルに複製する。

dp3 r, s1, s2    ; s1 と s2 の内積、全てのチャンネルに複製

dp3 命令は基本的にベクトル演算であるため、常にベクトル パイプラインで実行されることに注意すること。これをアルファ複製 ny入力引数修飾子 (.a) と共に使用した場合、この入力引数修飾子は単に結果がアルファ チャネルにも伝達されることを示す。つまり、dp3 はカラー処理も行う場合にのみアルファ処理として指定でき、同じ引数を使用しなければならない。

dp3 r0.rgb, t0, v0
dp3 r0.a,   t0, v0

または、次のようにしても同じである。

dp3 r0, t0, v0

この場合、dp3 演算のグレースケールの結果が、r0 のカラー チャネルとアルファ チャネルの両方にコピーされる。

結果のアルファ チャネルでは、異なる命令を指定できる。

dp3 r0.rgb, t0, v0
mul r0.a,   t0, v0

dp3 命令は、入力引数が符号付き動的範囲に展開されていない場合、通常、入力引数に適用された符号化スケーリング入力引数修飾子 (_bx2) を利用する。ライティングについて使用する場合は、通常、次の例のように、彩度命令修飾子 (_sat) を使用して負の値を黒に制限する。

dp3_sat r0, t0_bx2, v0_bx2    ; t0 はバンプ、v0 はライトの方向ベクトル


lrp

第 1 ソース レジスタで指定された割合で、第 2 および第 3 ソース レジスタの間を線形補間する。

lrp   tDest, tSrc0, tSrc1, tSrc2

レジスタ

tDest
処理の結果を保持するデスティネーション レジスタ。
tSrc0
入力引数を指定するソース レジスタ。
tSrc1
入力引数を指定するソース レジスタ。
tSrc2
入力引数を指定するソース レジスタ。

注意

この命令は、次の公式に基づいて線形補間を行う。

tSrc0 * tSrc1 + (1-tSrc0) * tSrc2 = tSrc2 + tSrc0 * (tSrc1 - tSrc2)

次の例は、この命令の使い方を示している。

lrp d, s0, s1, s2    ; d = s0*s1 + (1-s0)*s2 = s2 + s0*(s1-s2)


mad

最後の 2 つのソース オペランド レジスタで指定されている 2 つの色の積に、第 1 ソース レジスタを追加した値をロードする。

mad   tDest, tSrc0, tSrc1, tSrc2

レジスタ

tDest
処理の結果を保持するデスティネーション レジスタ。
tSrc0
入力引数を指定するソース レジスタ。
tSrc1
入力引数を指定するソース レジスタ。
tSrc2
入力引数を指定するソース レジスタ。

注意

この命令は、複数操作の蓄積を行う。最初の 2 つの引数を掛け、それに残った入力ソース引数を足し、その結果をレジスタに書き込む。

この命令は、次の公式に基づいて乗算と加算を行う。

tSrc0 * tSrc1 + tSrc2

次の例は、この命令の使い方を示している。

mad  d, s0, s1, s2;    d = s0 * s1 + s2


mov

ソース レジスタの値をロードする。

mov   tDest, tSrc0

レジスタ

tDest
処理の結果を保持するデスティネーション レジスタ。
tSrc0
入力引数を指定するソース レジスタ。

注意

次の例は、この命令の使い方を示している。

mov   d, s    ; s を d にコピー ( d = s )


mul

デスティネーション レジスタに、ソース オペランド レジスタの 2 色の要素単位の内積をロードする。

mul   tDest, tSrc0, tSrc1

レジスタ

tDest
処理の結果を保持するデスティネーション レジスタ。
tSrc0
入力引数を指定するソース レジスタ。
tSrc1
入力引数を指定するソース レジスタ。

注意

この命令は、乗算処理を行うものである。

次の例は、この命令の使い方を示している。

mul  d, s1, s2    ; 乗算 d = s1*s2


sub

ソース オペランドの 2 つの色の差をロードする。

sub   tDest, tSrc0, tSrc1

レジスタ

tDest
処理の結果を保持するデスティネーション レジスタ。
tSrc0
入力引数を指定するソース レジスタ。
tSrc1
入力引数を指定するソース レジスタ。

注意

この命令は、次の公式に基づいて減算を行う。

tDest = tSrc0 - tSrc1

次の例は、この命令の使い方を示している。

sub   d, s1, s2    ; 差


バージョンおよび定数定義命令

Direct3DX ピクセル シェーダ アセンブラには、シェーダのタイプおよびバージョンを識別したり、ピクセル シェーダで使用する定数を定義するための命令が用意されている。

def | 定数を定義する
ps | バージョンおよびタイプ

バージョン命令は、各シェーダの先頭にある必要がある。

定数定義命令は、バージョン命令の実行後、ほかのすべての命令よりも前に実行しなければならないことに注意すること。


def

ピクセル シェーダで使用する定数を定義するためのメソッドを提供する。

def   vDest, fVal0, fVal1, fVal2, fVal3

レジスタ

vDest
処理の結果を保持するデスティネーション レジスタ。
fVal0
入力引数を指定するソース レジスタ。
fVal1
入力引数を指定するソース レジスタ。
fVal2
入力引数を指定するソース レジスタ。
fVal3
入力引数を指定するソース レジスタ。

注意

次の例は、def 命令の使い方を示している。def 命令は、ほかのシェーダの命令より前に置く必要がある。

Ps.1.0
def c0, 0.0f, 0.0f, 0.0f, 1.0f
def c7, 1.0f, 2.0f, 3.0f, 4.0f
tex t0
mov r0, t0

これらの定数は命令ストリームで定義される。


ps

シェーダ コードのタイプおよびバージョンを指定するためのメソッドを提供する。

ps.mainVer.subVer

レジスタ

mainVer
ピクセル シェーダのメイン バージョン番号。
subVer
ピクセル シェーダのサブ バージョン番号。

注意

次の例は、ps 命令の使い方を示している。

ps.1.0  ; ピクセル シェーダ バージョン 1.0.

この命令は、すべてのピクセル シェーダの先頭にある必要がある。


テクスチャ アドレッシング命令

ここでは、Direct3DX ピクセル シェーダ アセンブラが実装するテクスチャ アドレッシング命令についてのリファレンス情報を記述する。テクスチャ アドレッシング命令は、(テクスチャ カラー座標に対立するものとして) テクスチャ アドレス データを操作できるようにするために用意されている。

サンプリング ステージのテクスチャ セットは、Microsoft® Direct3D® アプリケーション プログラミング インターフェイス (API) のテクスチャ ステージ ステートによって選択されるサンプリング、フィルタリング、およびラッピング モードを使って、対応するテクスチャからサンプリングされる。テクスチャをサンプリングするときに、テクスチャのサンプリングに使用するアドレスに適用できる処理もある。これらの処理は、テクスチャ アドレッシング処理と呼ばれる。

次の表は、テクスチャ アドレッシング命令およびテクスチャ補正処理のサブセットを示している。

命令 | 説明
tex | 変更なし
texbem | バンプ環境マップ
texbeml | 輝度付きバンプ環境マップ
texcoord | テクスチャ座標
texkill | ピクセルのマスク アウト
texm3x2pad | 3 × 2 行列乗算への入力
texm3x2tex | 3 × 2 行列乗算の結果
texreg2ar | アルファ成分および赤成分の再マッピング
texreg2gb | 緑成分および青成分の再マッピング

さらに、ピクセル シェーダ API は、テクスチャからサンプリングされたベクトルについてのピクセル単位の 3 × 3 行列乗算を実行する多くのメソッドをサポートする。3 × 3 行列は、3 つの連続するテクスチャ宣言ステージのテクスチャ座標で構成されている。これらの行列乗算演算は、複数のテクスチャ アドレス処理から構築される。

次の表は、ピクセル単位の 3 × 3 行列乗算に関連する、残りのテクスチャ アドレッシング命令を示している。

命令 | 説明
texm3x3pad | 3 × 3 行列乗算への入力
texm3x3spec | スペキュラ反射と環境マッピング
texm3x3tex | 3 × 3 行列乗算の結果
texm3x3vspec | 固定視点ベクトルを含まないスペキュラ反射/環境マッピング

テクスチャ アドレス命令は、宣言/定義したテクスチャ アドレスになる出力引数 (結果) を定義する。一部の命令では、入力オペランドを指定する必要がある。この入力オペランドは、定義済みのテクスチャでなければならない。これらは、テクスチャ サンプリング ユニットによって、カラー処理/アルファ処理/ブレンディング シェーダに放出されるテクスチャ カラーの宣言と考えられる。これらのテクスチャ レジスタは、定義済みのテクスチャで宣言できるが、後のテクスチャ、またはその他のピクセル カラー レジスタとしては宣言できない。

すべてのテクスチャ アドレス処理は、テクスチャを定義した順序で宣言しなければならない。テクスチャ アドレス処理では、それより後にある別のテクスチャ (つまり、ステージ番号がより大きなテクスチャ) を参照することはできない。

パフォーマンスに関する注意 テクスチャ アドレッシング処理では、テクスチャ アドレスを表すのに十分な精度をサポートしている必要がある。たとえば、デバイスでサポートされている最大テクスチャ ディメンジョンの環境マップで、テクセルの一部に対して補正できるバンプ環境マッピング行列の要素で補正を表現するのに十分な精度でなければならない。また、これらの処理で補間されるすべての量は、パースペクティブ補正を使って補間しなければならない。


tex

テクスチャから色をサンプリングし、サンプリングに使用したアドレスは変更しないで対応するレジスタにコピーする。

tex   tDest

レジスタ

tDest
処理の結果を保持するデスティネーション レジスタ。

注意

この命令がデフォルトなので、ほかの命令によってサンプリングが指定されていないすべてのテクスチャに対しては、tex 命令の適用が想定される。

次の例は、この命令の使い方を示している。

tex r0    ; ステージ 0 でセットされているテクスチャから
          ; レジスタ 0 を宣言

この命令は、このテクスチャ ステージに対応する割り当て済みのテクスチャである無名の入力を取ることに注意すること。


texbem

入力引数で定義されている色を、DuDv 摂動データとして使用する。

texbem   tDest, tSrc0

レジスタ

tDest
処理の結果を保持するデスティネーション レジスタ。
tSrc0
入力引数を指定するテンポラリ ソース レジスタ。

注意

texbem 命令は、u 成分と v 成分を 2D バンプ環境マッピング行列でトランスフォームし、それを現在のステージのテクスチャ座標に追加し、現在のステージのテクスチャをサンプリングする。

tex    t0        ; テクスチャからサンプルするよう t0 を定義
texbem t1, t0    ; u = u1 + mat00*r0.r + mat01*r0.g, と
                 ; v = v1 + mat10*r0.r + mat11*r0.g を計算
                 ; 次に u,v でサンプル、 r0.b は無視される
mov r0, t1       ; 最終結果を出力色にコピー

この処理は常に du および dv を符号付きの数値として解釈するので、入力引数について符号化スケーリング入力修飾子 (_bx2) を入力引数として指定する必要はない。テクスチャは 2 番目のステージで設定され、最初のステージで設定されたテクスチャは無視される。

この命令は、ピクセル単位の環境マッピングやディフューズ ライト (バンプ マッピング)、環境マッティングなど、アドレス補正に基づくさまざまな技法に使用できる。

この処理は 2 つの命令のマクロである (2 ステージ/スロットを消費する)。u' = u + du*M00 + dv*M01 および v' = v + du*M10 + dv*M11 で、M00、M01、M10、および M11 は D3DTSS_BUMPENVMAT00、D3DTSS_BUMPENVMAT01、D3DTSS_BUMPENVMAT10、および D3DTSS_BUMPENVMAT11 である。

この命令は、このテクスチャ ステージに対応する割り当て済みのテクスチャである無名の入力を取ることに注意すること。


texbeml

前のステージでサンプリングされた色を、輝度情報付きの DuDvL 摂動データとして使用する。

texbeml   tDest, tSrc0

レジスタ

tDest
処理の結果を保持するデスティネーション レジスタ。
tSrc0
入力引数を指定するテンポラリ ソース レジスタ。

注意

texbeml 命令は、色の赤成分と緑成分を 2D バンプ環境マッピング行列でトランスフォームし、その成分を現在のステージのテクスチャ座標に追加し、作成された 2D アドレスでこのテクスチャをサンプリングする。次に、輝度 (L) および Microsoft® Direct3D® API 指定の輝度とバイアス テクスチャ ステージの値を使って、輝度修正を適用する。

次のピクセル シェーダでは、デスティネーション レジスタに設定される色は、ステージ 1 で設定されたテクスチャ マップから取得されて、赤チャネルと緑チャネルの値で補正されたアドレスによってインデックス付けされて、ステージ 0 で設定されたマップからサンプリングされた色として定義される。

tex     t0        ; 3 要素 DuDvL を取得するため t0 を定義
texbeml t1, t0    ; u = u1 + mat00*r0.r + mat01*r0.g と
                  ;  v = v1 + mat10*r0.r + mat11*r0.g を計算
                  ; 次に u,v でサンプル、r0.b は無視される
                  ; 次に輝度修正を適用
mov r0, t1        ; 最終結果を出力色にコピー

テクスチャは 2 番目のステージで設定され、最初のステージで設定されたテクスチャは無視される。

この処理は 2 つの命令のマクロである (2 ステージ/スロットを消費する)。u' = u + du*M00 + dv*M01 および v' = v + du*M10 + dv*M11 で、M00、M01、M10、および M11 は D3DTSS_BUMPENVMAT00、D3DTSS_BUMPENVMAT01、D3DTSS_BUMPENVMAT10、および D3DTSS_BUMPENVMAT11 である。

この命令は、このテクスチャ ステージに対応する割り当て済みのテクスチャである無名の入力を取ることに注意すること。


texcoord

このステージに対して割り当てられた補間されたテクスチャの座標を、ブレンディングで使用する色に変換する。

texcoord   tDest

レジスタ

tDest
処理の結果を保持するデスティネーション レジスタ。

注意

この命令を使うと、テクスチャ座標を追加グーロー補間 (保証されたパースペクティブ補正) 色として使用できる。

texcoord  t0    ; テクスチャ座標からカラーとして t0 を宣言

頂点シェーダは任意の量をテクスチャ座標にマッピングできるので、texcoord 命令を使うと、位置、法線、光源方向などの任意のデータをピクセル シェーダにストリームできる。

この命令は、このテクスチャ ステージに対応する割り当て済みのテクスチャである無名の入力を取ることに注意すること。


texkill

任意のテクスチャ座標が 0 より小さい場合、ピクセルをマスク アウトする。

texkill   tDest

レジスタ

tDest
処理の結果を保持するデスティネーション レジスタ。

この命令を使って、ラスタライザで任意のクリップ面を実装できる。

頂点シェーダを使用する場合、アプリケーションはパースペクティブ トランスフォームを適用する必要がある。不等形のスケーリング係数が含まれている場合、クリップ面もトランスフォームする必要があるので、任意のクリップ面では問題が発生することがある。したがって、任意クリップ面で使用するには、texkill 演算子で識別されるテクスチャ座標セットである非射影頂点位置を提供するのが最適である。

この命令は、このテクスチャ ステージに対応する割り当て済みのテクスチャである無名の入力を取ることに注意すること。


texm3x2pad

2 × 3 行列乗算を実行するために、ほかのテクスチャ アドレス処理と組み合わせて使用される。

texm3x2pad   tDest, tSrc0

レジスタ

tDest
処理の結果を保持するデスティネーション レジスタ。
tSrc0
入力引数を指定するテンポラリ ソース レジスタ。

注意

この命令は、テクスチャ座標だけが使用されるステージを表すために使用される。これらの対応するステージにはテクスチャはバインドされていないので、サンプリングは行われない。入力引数 t0 は指定する必要がある。

次の例は、texm3x2pad 命令の使い方を示している。

tex t0             ; 標準的な 3 ベクトルとして t0 を定義
texm3x2pad t1, t0  ; 行列の第 1 行の乗算を実行
texm3x2tex t2, t0  ; 行列の第 2 行の乗算を実行し、
                   ; テクスチャ 2 としてサンプルする 2 ベクトルを取得

この命令は、このテクスチャ ステージに対応する割り当て済みのテクスチャである無名の入力を取ることに注意すること。


texm3x2tex

入力色ベクトルに対して 3 × 2 行列乗算を実行する。

texm3x2tex   tDest, tSrc0

レジスタ

tDest
処理の結果を保持するデスティネーション レジスタ。
tSrc0
入力引数を指定するテンポラリ ソース レジスタ。

注意

texm3x2tex 命令は、指定された入力色を取得し、入力色とそのステージのテクスチャ座標 (u、v、および w) の内積を計算して、u 座標を生成する。次に、同じ入力色を取得し、入力色とこのステージのテクスチャ座標の内積を計算して、v 座標を得る。最後に、このステージのテクスチャを (u、v) でサンプリングして、最終的な色を生成する。前のステージではテクスチャはサンプリングされておらず、また前のステージでテクスチャを設定する必要はなく、テクスチャに割り当てられているすべての演算子はこの演算によって無効になる。

次の例は、texm3x2tex 命令の使い方を示している。

tex t0             ; 標準的な 3 ベクトルとして t0 を定義
texm3x2pad t1, t0  ; 行列の第 1 行の乗算を実行
texm3x2tex t2, t0  ; 行列の第 2 行の乗算を実行し、
                   ; テクスチャ 2 としてサンプルする 2 ベクトルを取得
mov r0, t2

バンプ (通常の) マップはステージ 0 で設定し、標準の 2D テクスチャはステージ 2 で設定する必要がある。ステージ 1 で設定されるテクスチャは、すべて無視される。たとえば、次のシェーダでは、ベース テクスチャはディフューズ バンプ マップを乗算し、指数スペキュラを追加することによってライティングされている。ステージ 0 ではベース テクスチャを設定し、ステージ 1 では法線マップを設定し、ステージ 2 ではもう一度法線マップを設定している。

ps.1.0                 ; DirectX8 バージョン
tex t0                 ; サンプル法線マップ
texm3x2pad t1, t0_bx2  ; ライト ベクトルによる内積
texm3x2tex t2, t0_bx2  ; 半ベクトルとサンプルによる内積
mov r0, t2

設定 0 のテクスチャ座標はバンプ マップに位置する。テクスチャ座標セット 1 および 2 は、行列の行である。

この命令は、このテクスチャ ステージに対応する割り当て済みのテクスチャである無名の入力を取ることに注意すること。


texm3x3pad

テクスチャがバインドされていない 3 × 3 行列乗算の行で使用される処理を表す。

texm3x3pad   tDest, tSrc0

レジスタ

tDest
処理の結果を保持するデスティネーション レジスタ。
tSrc0
入力引数を指定するテンポラリ ソース レジスタ。

注意

この命令は、ピクセル シェーダのテクスチャ宣言ステージで実行される 3 × 3 行列乗算処理の一部である。宣言済みテクスチャに対応するテクスチャ座標は行列の行として使用される。このステージでは、いずれのテクスチャもバインドすべきではない。

この宣言に対する入力引数である t0 は、以下のピクセル シェーダの例に示すように、行列の乗算に対する入力引数である tSrc0 に指定しなければならない。

tex t0             ; 標準的な 3 ベクトルとして t0 を定義
texm3x3pad t1, t0  ; 行列の第 1 行の乗算を実行
texm3x3pad t2, t1  ; 行列の第 2 行の乗算を実行
texm3x3tex t3, t2  ; 行列の第 3 行の乗算を実行し、
                   ; テクスチャ 2 としてサンプルする 3 ベクトルを取得
mov r0, t3

この命令は、このテクスチャ ステージに対応する割り当て済みのテクスチャである無名の入力を取ることに注意すること。


texm3x3spec

スペキュラ反射と環境マッピングを実行する。

texm3x3spec   tDest, tSrc0, tSrc1

レジスタ

tDest
処理の結果を保持するデスティネーション レジスタ。
tSrc0
入力引数を指定するソース レジスタ。
tSrc1
入力引数を指定するソース レジスタ。

注意

この処理は、結果として生成されるトランスフォーム後ベクトルを取得し、視線ベクトルを反映するための法線として使用する。視線ベクトルは、常にコンスタント カラー c0 である。その後、命令は、処理の結果を、そのステージで設定されているキューブ テクスチャを参照するためのアドレスとして使用する。スペキュラ環境マップはプリロードされている。

tex t0                  ; 標準的な 3 ベクトルとして t0 を定義
texm3x3pad t1, t0       ; 行列の第 1 行の乗算を実行
texm3x3pad t2, t0       ; 行列の第 2 行の乗算を実行
texm3x3spec t3, t0, c0  ; 行列の第 3 行の乗算を実行し、
                        ; 反射計算を行い、テクスチャ 3 をサンプルする
mov r0, t3              ; 最終結果を出力色としてコピー

バンプ (通常の) マップはステージ 0 で設定される必要があり、キューブ テクスチャはステージ 3 で設定される必要がある。ステージ 1 または 2 で設定されるテクスチャはいずれも無視される。

設定 0 のテクスチャ座標はバンプ マップに位置する。1、2、および 3 を設定するテクスチャ座標は 3 × 3 行列の行である。

この命令は、このテクスチャ ステージに対応する割り当て済みのテクスチャである無名の入力を取ることに注意すること。

参照

texm3x3vspec


texm3x3tex

最後の 3 × 3 行列乗算の結果を返す。

texm3x3tex   tDest, tSrc0
tDest
処理の結果を保持するデスティネーション レジスタ。
tSrc0
入力引数を指定するテンポラリ ソース レジスタ。

注意

texm3x3tex 命令は、ピクセル シェーダのテクスチャ宣言において実行される 3 × 3 行列乗算処理を表す 3 つの命令の最後のものとして使われる。この命令の結果には、命令を実行した結果生じるトランスフォームされたベクトルが含まれる。この宣言に対する入力引数には、行列の乗算に対する入力を指定しなければならない。このステージに割り当てられたテクスチャ座標は、行列の行として使用される。

3 × 3 行列は、このステージおよび前の 2 つのステージのテクスチャ座標で構成されている。結果として得られる 3 要素ベクトルを使い、このステージで割り当てられているテクスチャ (キューブ テクスチャまたはボリューム テクスチャ) にインデックスを設定して、最終的な色を生成する。前の 2 つのステージからはテクスチャ カラーはサンプリングされず、これらのステージに割り当てられていた演算子はすべて無効になる。

tex t0             ; 標準的な 3 ベクトルとして t0 を定義
texm3x3pad t1, t0  ; 行列の第 1 行の乗算を実行
texm3x3pad t2, t0  ; 行列の第 2 行の乗算を実行
texm3x3tex t3, t0  ; 行列の第 3 行の乗算を実行

dp3 r0, t0, v0     ; v0 を使ってディフューズ ライティング強度を計算

バンプ (通常の) マップはステージ 0 で設定される必要があり、キューブ テクスチャはステージ 3 で設定される必要がある。ステージ 1 または 2 で設定されるテクスチャはいずれも無視される。

設定 0 のテクスチャ座標はバンプ マップに位置する。1、2、および 3 を設定するテクスチャ座標は 3 × 3 行列の行である。

この命令は、このテクスチャ ステージに対応する割り当て済みのテクスチャである無名の入力を取ることに注意すること。


texm3x3vspec

視点ベクトルが固定していないときのスペキュラ反射および環境マッピングを行う。

texm3x3vspec   tDest, tSrc0

レジスタ

tDest
処理の結果を保持するデスティネーション レジスタ。
tSrc0
入力引数を指定するソース レジスタ。

注意

この命令はテクスチャ アドレッシングに使用する。行列の行として使われる 3 つのテクスチャ座標の w 要素から視線が取得される点を除き、この命令の動作は texm3x3spec とまったく同じである。

tex t0               ; 標準的な 3 ベクトルとして t0 を定義
texm3x3pad t1, t0    ; 行列の第 1 行の乗算を実行
texm3x3pad t2, t0    ; 行列の第 2 行の乗算を実行
texm3x3vspec t3, t0  ; 行列の第 3 行の乗算を実行し、
                     ; テクスチャ 2 をサンプルし、反射計算を行い、
                     ; テクスチャ 3 をスペキュラ マップとしてサンプル
mov r0.rgb, t3       ; スペキュラ色を結果に入れる
mov r0.a,   t3       ; ディフーズ色をアルファ チャネルに入れる

バンプ (通常の) マップはステージ 0 で設定される必要があり、キューブ テクスチャはステージ 3 で設定される必要がある。ステージ 1 または 2 で設定されるテクスチャはいずれも無視される。

設定 0 のテクスチャ座標はバンプ マップに位置する。1、2、および 3 を設定するテクスチャ座標は 3 × 3 行列の行である。

この命令は、このテクスチャ ステージに対応する割り当て済みのテクスチャである無名の入力を取ることに注意すること。

参照

texm3x3spec


texreg2ar

指定された入力色ベクトルのアルファ成分と赤成分で指定される 2D 座標で、このステージのテクスチャをサンプリングする。

texreg2ar tDest, tSrc0

レジスタ

tDest
処理の結果を保持するデスティネーション レジスタ。
tSrc0
入力引数を指定するテンポラリ ソース レジスタ。

注意

この命令は、色空間の再マッピング処理で便利である。

この命令は、このテクスチャ ステージに対応する割り当て済みのテクスチャである無名の入力を取ることに注意すること。


texreg2gb

指定された入力色ベクトルの緑成分と青成分で指定される 2D 座標で、このステージのテクスチャをサンプリングする。

texreg2gb tDest, tSrc0

レジスタ

tDest
処理の結果を保持するデスティネーション レジスタ。
tSrc0
入力引数を指定するテンポラリ ソース レジスタ。

注意

この命令は、色空間の再マッピング処理で便利である。

この命令は、このテクスチャ ステージに対応する割り当て済みのテクスチャである無名の入力を取ることに注意すること。


修飾子

Direct3DX ピクセル シェーダ アセンブラでは、次のタイプの修飾子がサポートされている。

  • 引数修飾子
  • 命令修飾子


引数修飾子

Direct3DX ピクセル シェーダ アセンブラは、命令引数 (オペランド) および命令で処理される前の入力引数に影響する修正子フラグを取ることができる。入力引数修飾子には 2 つのタイプがある。色およびアルファ ブレンディング入力引数修飾子とテクスチャ アドレッシング入力引数修飾子である。

入力引数修飾子は、次の表で定義されている。rn. は入力引数 (レジスタ) である。

命令 | 構文 | 説明
アルファ複製 | rn.a | アルファ チャネルをすべての色に複製する。
補数 | 1-rn | 補数を計算する (y = 1.0 - x)。符号なし x が必要。
正負の反転 | -rn | 値の正負を反転する (y = -x)。符号付き x が必要。
バイアス | rn_bias | 値を ｽ 下にシフトする。y = (x-0.5)。
符号化スケーリング | rn_bx2 | 値を下にシフトし、データを 2 倍にスケーリングする。y = 2*(x-0.5)。

たとえば、lrp 命令は、入力引数修飾子を使って実装できる。

; ディフューズ アルファを使って、r0 と t0 ブレンドすると、
lrp r0, v0.a, r0, t0
; (より多くのクロックを使って) 次のように書き込むことができる。
sub r0, r0, t0
mad r0, t0, v0.a, r0

頂点シェーダとは異なり、ピクセル シェーダは成分の入れ換えをサポートしていない。x、y、および z の各要素はまとめて RGB 色成分として扱われて、w 要素は個別に転送できるアルファとして扱われる。


アルファ複製

rn.a

命令を処理する前に、影響を受けるレジスタのアルファ チャネルを、すべてのカラー チャネルに複製する。

次の例は、この修飾子の使い方を示している。

mul r0, r0, r1.a    ; アルファ チャネルで乗算 (グレースケール)
                    ; 色の強度だけを変化

この演算子は補数または正負の反転演算子と組み合わせて使用できることに注意すること。この演算子の機能は、Microsoft® DirectX® 6.0 および 7.0 マルチテクスチャ構文の D3DTA_ALPHAREPLICATE フラグに似ている。

この修飾子は、色およびアルファ ブレンディング命令で使用するためのものである。


補数

1-rn

指定されたレジスタの各チャネルで色の補数を計算する。

次の例は、この修飾子の使い方を示している。

mul r0, r0, 1-r1    ; (1.0 - r1) で乗算する。

入力データが符号なしの場合、つまり 0 から 1 の範囲にある場合、この修飾子はあらかじめ定義されている結果のみ生成する。この処理は、同じ引数にその他すべての修飾子が提示された後で実行される。

この愁傷子は、符号なしデータについてのみ機能することに注意すること。この命令には、バイアス、符号化スケーリング、および正負の反転修飾子との整合性がないので、同じレジスタでこれらの修飾子と同時に使用することはできない。

この修飾子は、色およびアルファ ブレンディング命令で使用するためのものである。


正負の反転

rn

符号の反転 (y = -x) を実行する。つまり、命令で値を使用する前に正負を反転する。

次の例は、この修飾子の使い方を示している。

mul r0, r0, -v1    ; マイナスのスペキュラ色で乗算する。

この処理は、同じ引数に対するほかの修飾子の後に実行される。

補数 (1-rn)と正負の反転 (-rn) は相互に排他的であり、同じレジスタに適用することはできない。

この修飾子は、色およびアルファ ブレンディング命令で使用するためのものである。


バイアス

rn_bias

各チャネルを 1/2 下にシフトする。したがって、レジスタを処理する前に、y = (x-0.5) を実行する。

次の例は、この修飾子の使い方を示している。

add r0, r0, t0_bias    ; 0.5 シフト ダウン

この例では、add を使って、Microsoft® DirectX® 6.0 および 7.0 のマルチテクスチャ構文の D3DTOP_ADDSIGNED と同じ処理を実行する方法を示している。

この修飾子は、0 ～ 1 の範囲にあるデータを -0.5 ～ 0.5 の範囲になるように変更することと同じ効果がある。これは、一般的に詳細なテクスチャを適用するために使用される。また、入力データを符号付きの数値として処理し、範囲が -1 ～1 に制限されている実装環境でオーバーフロー クランプが発生する前に、動的範囲を保持することもできる。

この修飾子は補数と相互に排他的であるため、同じレジスタに適用することはできない。

この修飾子は、色およびアルファ ブレンディング命令で使用するためのものである。


符号化スケーリング

rn_bx2

色およびアルファ ブレンディング命令と共に使用する場合、この修飾子は、命令が実行される前に、各チャネルから 0.3 を減算し、その結果を 2.0 倍にスケーリングする。つまり、y = (x-0.5)*2 を実行する。

次の例は、この修飾子の使い方を示している。

dp3_sat r0, t1_bx2, v0_bx2    ; ディフューズ色 v0 にライト方向、
                              ; TL にバンプ法線を仮定した、パーピクセル
                              ; ライティング / バンプ マッピング

この修飾子は、0 から 1 までの範囲にあるデータを再マッピングして、-1 から 1 までの範囲にある符号付きデータにする。これにより、以降のデータ処理では実装の完全な符号付き動的範囲を使用できる。

この修飾子は、一般的に、内積命令 (dp3) への入力について使用される。

この修飾子は補数と相互に排他的であるため、同じレジスタに適用することはできない。

テクスチャ レジスタ宣言に対する入力引数では _bx2 修飾子をサポートしており、dp3、texm3x2tex、および texm3x3tex 処理の宣言/命令の実行中に行う追加の処理を指定できる。その他のテクスチャ アドレッシング演算子は、_bx2 入力引数修飾子をサポートしていない。

入力レジスタ引数を使用する前にバイアスおよびスケーリングの処理が必要があることを指定するには、入力レジスタ引数に _bx2 を追加する。

tex t0            ; テクスチャ カラーを読み込む。
dp3 t1, t0_bx2    ; このステージのテクスチャ座標で内積を計算する。

これは、入力レジスタを指定された演算子で使用する前に、入力レジスタに対して演算 y = 2(x - 0.5) を実行する。この演算は一般的に、-1 ～ 1 の範囲にある符号付きの値を含むように意図されているデータを平行移動するために使用されるが、ソースがこの演算をサポートできないので、実行しない。このようなデータ ソースには、テクスチャ (tn)、補間色 (vn)、テクスチャ座標、または固定要素レジスタ (cn) がある。

この修飾子は、色およびアルファ ブレンディング命令と、テクスチャ アドレッシング命令の両方で使用するためのものである。


命令修飾子

Direct3DX ピクセル シェーダ アセンブラは、シフト/スケーリング修正子フラグ、および生成される出力結果に影響する彩度修正子フラグをサポートしている。命令修飾子は、次の順序で命令処理と結び付く。

  1. 補数を実行する。
  2. バイアスを適用する。
  3. 結果にスケーリングを適用する。
  4. クランプを実行する。

シフト/スケーリング修飾子を使うと、結果の大きさをある範囲内で変更できる。

名前 | 修飾子
_x2 | 2 で乗算した結果
_x4 | 4 で乗算した結果
_d2 | 2 で除算した結果

さらに、色およびアルファ ブレンディング命令と、テクスチャ アドレッシング命令の両方で使用するために、彩度修飾子 (_sat) が用意されている。

色およびアルファ ブレンディング命令の場合、彩度修飾子は、この命令の結果を各成分について 0.0 ～ 1.0 の範囲にクランプする。次の例は、この修飾子の使い方を示している。

dp3_sat r0, t0_bx2, v0_bx2    ; t0 はバンブ、v0 はライト方向

この処理は、スケーリング命令修飾子の後で実行される。これは、通常、内積の結果をクランプするために使用される。ただし、フレーム バッファが常に 0 ～ 1 の範囲にあるマルチパス メソッドと、彩度が各ステージで行われるように定義されている Microsoft® DirectX 6.0 および 7.0 のマルチテクスチャ構文で、一貫性のあるエミュレーションを実行できる。

テクスチャ アドレッシング命令の場合、彩度修飾子を処理に追加し、終了時の処理の結果を 0.0 ～ 1.0 の色の範囲にクランプするように指定できる。これは、一般的に、ライティング処理で使用する必要がある。次の例は、この修飾子の使い方を示している。

ps.1.0                       ; DirectX8 バージョン
tex t0                       ; テクスチャ カラーを読み込む
dp3_sat t1, t0_bx2, v0_bx2   ; テクスチャ座標とクランプで内積を計算

次の add 命令は、ソース オペランド (s0 と s1) の 2 つの色を加えたものをデスティネーション レジスタ (d) にロードし、結果に 2 を掛けている。

add_x2   d, s0, s1

次の add 命令は、ソース オペランド (s0 と s1) の 2 つの色を加えたものをデスティネーション レジスタ (d) にロードし、結果を各成分について 0.0 ～ 1.0 の範囲にクランプしている。

add_sat   d, s0, s1

次の add 命令は、ソース オペランド (s0 と s1) の 2 つの色を加えたものをデスティネーション レジスタ (d) にロードし、結果を 2 倍してから、各成分について結果を 0.0 ～ 1.0 の範囲にクランプしている。

add_2x_sat   d, s0, s1


出力書き込みマスク

Direct3DX ピクセル シェーダ コンパイラでサポートされている出力マスクは、この結果が結果の色またはアルファ成分のいずれかを更新しなければならないかどうか、およびその処理に色またはアルファ パイプラインを使うかどうかを指定するために使用される。これらの出力マスクは、Microsoft® DirectX 6.0 および 7.0 マルチテクスチャ ブレンディングの個別の色およびアルファ処理に似ている。

これらのフラグは頂点シェーダでサポートされているフラグほど一般的ではない。これは、rgb 成分が常に 1 つのフラグにグループ化されるため、.a と .rgb の 2 種類のマスクしか存在しないからである。

次の出力書き込みマスクがサポートされている。

  • 色/ベクトル書き込みマスク
  • アルファ/スカラー書き込みマスク
  • 完全書き込みマスク

テクスチャ アドレッシング命令では、出力書き込みマスクはサポートされていないことに注意すること。これらの処理は、常にデスティネーション レジスタの 4 つの成分を更新するので、r、g、b を分割できない。

ピクセル シェーダは、任意の入れ換えをサポートしておらず、色およびアルファ処理のみサポートしている。


色/ベクトル書き込みマスク

.rgb

出力レジスタについて指定した場合、このフラグは、処理でデスティネーション レジスタの 3 つのカラー チャネルだけを更新することを指定するので、命令の色 (ベクトル) パイプラインで実行する必要がある。

次の例は、この出力書き込みマスクの使い方を示している。

mul r0.rgb,  t0, v0
add r0.a,    t1, v1


アルファ/スカラー書き込みマスク

.a

デスティネーション レジスタについて指定した場合、このフラグは、処理でデスティネーション レジスタのアルファ チャネルだけを更新することを指定するので、この命令のアルファ (スカラー) パイプラインで実行する必要がある。

次の例は、この出力書き込みマスクの使い方を示している。

mul r0.rgb,  t0, v0
add r0.a,    t1, v1


完全書き込みマスク

.rgba

色およびアルファ チャネルの両方に同じ命令を適用することを要求する。これはデフォルトであり、これと同じ結果を得るために出力マスクを指定する必要はない。

たとえば、次の命令

mul r0, t0, v0

は、次の命令と同じであり、

mul r0.rgba, t0, v0

次の命令とも同じである。

  mul r0.rgb, t0, v0
+ mul r0.a,   t0, v0

この最後の構文でも、スカラー パイプラインとベクトル パイプラインをペアにしているため、1 クロックしか使用しない。詳細については、「ピクセル シェーダの命令のペア」を参照すること。


エフェクト ファイル形式

ここでは、C++ でのアプリケーション開発について説明する。


パラメータの型

ここでは、C++ でのアプリケーション開発について説明する。


定数値の構文

ここでは、C++ でのアプリケーション開発について説明する。


頂点シェーダ宣言の構文

ここでは、C++ でのアプリケーション開発について説明する。


有効なステートの一覧

ここでは、C++ でのアプリケーション開発について説明する。


X ファイル Visual Basic リファレンス

ここでは、Microsoft® DirectX® (.x) のファイルを扱うために使用される API 要素のリファレンス情報を記述する。

  • クラス
  • 列挙
  • エラー コード


クラス

ここでは、Microsoft® DirectX® (.x) のファイルに対する読み書きで使用されるクラスのリファレンス情報を記述する。

  • DirectXFile
  • DirectXFileBinary
  • DirectXFileData
  • DirectXFileEnum
  • DirectXFileObject
  • DirectXFileReference
  • DirectXFileSave


DirectXFile

DirectXFileEnumObject オブジェクトおよび DirectXFileSaveObject オブジェクトを作成してテンプレートを登録するには、DirectXFile クラスのメソッドを使用する。

DirectXFile クラスを取得するには、DirectX8.DirectXFileCreate メソッドを呼び出す。

DirectXFile クラスのメソッドは、以下のグループにまとめることができる。

生成 | CreateEnumObject
 | CreateSaveObject
テンプレート | RegisterDefaultTemplates
 | RegisterTemplates

DirectXFile クラスのグローバル ユニーク識別子 (GUID) は IID_IDirectXFile である。


DirectXFile.CreateEnumObject

列挙オブジェクトを作成する。

object.CreateEnumObject( _
    FileName As String) As DirectXFileEnum

指定項目

object
DirectXFile オブジェクトを表すオブジェクト式。
FileName
ファイル名に設定する String 値。

戻り値

作成された列挙オブジェクトを表す DirectXFileEnum オブジェクトを返す。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

DXFILEERR_BADALLOC
DXFILEERR_BADFILEFLOATSIZE
DXFILEERR_BADFILETYPE
DXFILEERR_BADFILEVERSION
DXFILEERR_BADRESOURCE
DXFILEERR_BADVALUE
DXFILEERR_FILENOTFOUND
DXFILEERR_RESOURCENOTFOUND
DXFILEERR_URLNOTFOUND

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

このメソッドを呼び出した後は、DirectXFileEnum 系メソッドのいずれかを使って、データ オブジェクトを取得する。

参照

DirectXFileEnum


DirectXFile.CreateSaveObject

保存オブジェクトを作成する。

object.CreateSaveObject( _
    FileName As String, _
    Flags As Long) As DirectXFileSave

指定項目

object
DirectXFile オブジェクトを表すオブジェクト式。
FileName
データの保存に使用するファイルを示す String 値。
Flags
DirectX ファイルの保存時に使用するフォーマットを示す CONST_DXFILEFORMATFLAGS 列挙のメンバ。

戻り値

作成された保存オブジェクトを表す DirectXFileSave オブジェクトを返す。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

DXFILEERR_BADALLOC
DXFILEERR_BADFILE
DXFILEERR_BADVALUE

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

このメソッドを使用した後は、DirectXFileSave クラスのメソッドを使用してデータ オブジェクトを作成し、テンプレートまたはデータを保存する。

ファイル フォーマットのデフォルト値は DXFILEFORMAT_BINARY である。ファイル フォーマットの値を論理和で結合し、圧縮テキスト ファイルまたは圧縮バイナリ ファイルを作成できる。バイナリ (0) とテキスト (1) の両方を指定した場合は、テキスト ファイル フォーマットの値と区別がつかないため (0 + 1 = 1)、テキスト ファイルとして保存される。ファイル フォーマットとしてテキストかつ圧縮を指定すると、ファイルは最初にテキストとして書き込まれた後、圧縮される。ただし、圧縮テキスト ファイルはバイナリ テキスト ファイルほど効率がよくないので、ほとんどの場合は、バイナリかつ圧縮を指定する必要がある。フォーマットを指定しないでファイルを圧縮するように設定すると、バイナリ圧縮ファイルが作成される。

参照

DirectXFileSave


DirectXFile.RegisterDefaultTemplates

デフォルト テンプレートを登録する。

object.RegisterDefaultTemplates()

指定項目

object
DirectXFile オブジェクトを表すオブジェクト式。

エラー コード

失敗した場合はエラーが発生し、Err.Number が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。


DirectXFile.RegisterTemplates

カスタム テンプレートを登録する。

object.RegisterTemplates( _
    TemplateData As Any, _
    Size As Long)

指定項目

object
DirectXFile オブジェクトを表すオブジェクト式。
TemplateData
テンプレートを含むテキスト フォーマットまたはバイナリ フォーマットの Microsoft® DirectX® ファイルで構成されるバッファ。
Size
TemplateData バッファのサイズ (バイト単位)。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

DXFILEERR_BADFILEFLOATSIZE
DXFILEERR_BADFILETYPE
DXFILEERR_BADFILEVERSION
DXFILEERR_BADVALUE
DXFILEERR_PARSEERROR

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

テンプレートはすべて、名前とユニバーサル ユニーク識別子 (UUID) を指定しなければならない。


DirectXFileBinary

バイナリ データを読み取ったり、バイナリ データについての情報を取得したりするには、DirectXFileBinary クラスのメソッドを使用する。

DirectXFileBinary クラスは、次のようなグループに分類できる DirectXFileObject メソッドを実装している。

情報 | GetId
 | GetName

IDirectXFileBinary オブジェクトのメソッドは、以下のグループにまとめることができる。

情報 | GetMimeType
 | GetSize
データの読み取り | Read

DirectXFileBinary クラスのグローバル ユニーク識別子 (GUID) は IID_IDirectXFileBinary である。


DirectXFileBinary.GetMimeType

バイナリ データの MIME (Multipurpose Internet Mail Extensions) タイプを取得する。

object.GetMimeType() As String

指定項目

object
DirectXFileBinary オブジェクトを表すオブジェクト式。

戻り値

ファイルの MIME タイプが設定されている String 値を返す。

エラー コード

失敗した場合はエラーが発生し、Err.Number に DXFILEERR_BADVALUE が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

バイナリ オブジェクトに対する Microsoft® DirectX® ファイルで MIME タイプが指定されていない場合は、関数から空の文字列が返る。


DirectXFileBinary.GetSize

バイナリ データのサイズを取得する。

object.GetSize() As Long

指定項目

object
DirectXFileBinary オブジェクトを表すオブジェクト式。

戻り値

バイナリ データのサイズが設定されている Long 値を返す (バイト単位)。

エラー コード

失敗した場合はエラーが発生し、Err.Number に DXFILEERR_BADVALUE が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。


DirectXFileBinary.Read

バイナリ データを読み取る。

object.Read( _
    Data As Any, _
    Size As Long) As Long

指定項目

object
DirectXFileBinary オブジェクトを表すオブジェクト式。
Data
読み取ったデータを受け取るバッファ。
Size
Data のバッファ サイズ (バイト単位) を保持する Long 値。

戻り値

実際に読み取ったバイト数が設定された Long 値を返す。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

DXFILEERR_BADVALUE
DXFILEERR_NOMOREDATA

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。


DirectXFileData

データ オブジェクトの直接階層を構築したり、直接階層にアクセスしたりするには、DirectXFileData クラスのメソッドを使用する。テンプレートの制約により階層が決まる。テンプレートによって許可されるデータ型のことを、オプション メンバと呼ぶ。オプション メンバは必須ではないが、オプション メンバがないと、オブジェクトで重要な情報が不足する場合がある。オプション メンバは、データ オブジェクトの子として保存される。子は、別のデータ オブジェクト、以前のデータ オブジェクトへの参照、またはバイナリ オブジェクトである。

DirectXFileData クラスは、次のようなグループに分類できる DirectXFileObject メソッドを実装している。

情報 | GetId
 | GetName

DirectXFileData クラスのメソッドは、以下のグループにまとめることができる。

データの追加 | AddBinaryObject
 | AddDataObject
 | AddDataReference
情報 | GetDataSize
 | GetType
データの取得 | GetData
 | GetDataFromOffset
 | GetNextObject

DirectXFileData クラスのグローバル ユニーク識別子 (GUID) は IID_IDirectXFileData である。


DirectXFileData.AddBinaryObject

バイナリ オブジェクトを作成し、子オブジェクトとして追加する。

object.AddBinaryObject( _
    Name As String, _
    GuidObject As String, _
    MimeType As String, _
    Data As Any, _
    Size As Long)

指定項目

object
DirectXFileData オブジェクトを表すオブジェクト式。
Name
オブジェクト名を保持する String 値。オブジェクトに名前が必要ない場合は、空の文字列を指定する。
GuidObject
オブジェクトを表すグローバル ユニーク識別子 (GUID) を保持する String 値。オブジェクトに GUID が必要ない場合は、空の文字列を指定する。
MimeType
オブジェクトの MIME タイプを保持する String 値。
Data
オブジェクトのデータを保持するバッファ。
Size
Data のバッファ サイズ (バイト単位) を保持する Long 値。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

DXFILEERR_BADALLOC
DXFILEERR_BADVALUE

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

参照

DirectXFileBinary.GetMimeType


DirectXFileData.AddDataObject

子オブジェクトとしてデータ オブジェクトを追加する。

object.AddDataObject( _
    Data As DirectXFileData)

指定項目

object
DirectXFileData オブジェクトを表すオブジェクト式。
Data
子オブジェクトとして追加するファイル データ オブジェクトを表す DirectXFileData オブジェクト。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

DXFILEERR_BADALLOC
DXFILEERR_BADVALUE

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

このメソッドを呼び出す前に、DirectXFileSave.CreateDataObject メソッドを使用して DirectXFileData オブジェクトを作成する。

参照

DirectXFileSave.CreateDataObject


DirectXFileData.AddDataReference

データ参照オブジェクトを作成し、子オブジェクトとして追加する。

object.AddDataReference( _
    Name As String, _
    Guid As String)

指定項目

object
DirectXFileData オブジェクトを表すオブジェクト式。
Name
参照されるデータ オブジェクトの名前を保持する String 値。Guid でグローバル ユニーク識別子 (GUID) への参照を指定する場合、このパラメータには空の文字列を指定できる。
Guid
データを表す GUID を保持する String 値。Name で名前の参照を指定する場合、このパラメータには空の文字列を指定できる。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

DXFILEERR_BADALLOC
DXFILEERR_BADVALUE

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

このメソッドが成功するには、パラメータ Name と Guid のどちらか一方が空ではない文字列でなければならない。


DirectXFileData.GetData

オブジェクトのメンバの 1 つに対するデータ、またはすべてのメンバに対するデータを取得する。

object.GetData( _
    Name As String, _
    Data As Any)

指定項目

object
DirectXFileData オブジェクトを表すオブジェクト式。
Name
データを取得するメンバの名前を保持する String 値。全必須メンバのデータを取得する場合は、空の文字列を指定する。
Data
Name に関連付けられているデータを受け取るバッファ。Name が空の文字列の場合、Data は、全必須メンバのデータが格納されている連続したメモリ ブロックのバッファに設定される。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

DXFILEERR_BADARRAYSIZE
DXFILEERR_BADDATAREFERENCE
DXFILEERR_BADVALUE

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

このメソッドを使うと、データ オブジェクトの必須メンバのデータを取得できるが、オプション (子) メンバのデータは取得できない。子オブジェクトを取得するには DirectXFileData.GetNextObject を使用する。

参照

DirectXFileData.GetNextObject


DirectXFileData.GetDataFromOffset

指定されたオフセットから始まるデータを取得する。

object.GetDataFromOffset( _
    Name As String, _
    Offset As Long, _
    ByteCount As Long, _
    Data As Any)

指定項目

object
DirectXFileData オブジェクトを表すオブジェクト式。
Name
データを取得するメンバの名前を保持する String 値。全必須メンバのデータを取得する場合は、空の文字列を指定する。
Offset
データ バッファにオフセットを保持する Long 値。
ByteCount
取得するデータのサイズ (バイト単位)。
Data
Name に関連付けられているデータを受け取るバッファ。Name が空の文字列の場合、Data は、全必須メンバのデータが格納されている連続したメモリ ブロックのバッファに設定される。

エラー コード

失敗した場合はエラーが発生し、Err.Number が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

参照

DirectXFileData.GetDataSize


DirectXFileData.GetDataSize

指定されたメンバのデータ サイズを取得する。

object.GetDataSize( _
    Name As String) As Long

指定項目

object
DirectXFileData オブジェクトを表すオブジェクト式。
Name
データ サイズを取得するメンバの名前を保持する String 値。

戻り値

データ サイズが設定された Long 値を返す (バイト単位)。

エラー コード

失敗した場合はエラーが発生し、Err.Number が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。


DirectXFileData.GetNextObject

Microsoft® DirectX® ファイル中の次の子データ オブジェクト、データ参照オブジェクト、またはバイナリ オブジェクトを取得する。

object.GetNextObject() As DirectXFileObject

指定項目

object
DirectXFileData オブジェクトを表すオブジェクト式。

戻り値

取得した子オブジェクトのファイル オブジェクトを表す DirectXFileObject オブジェクトを返す。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

DXFILEERR_BADVALUE
DXFILEERR_NOMOREOBJECTS

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。


DirectXFileData.GetType

オブジェクトのテンプレートのグローバル ユニーク識別子 (GUID) を取得する。

object.GetType() As String

指定項目

object
DirectXFileData オブジェクトを表すオブジェクト式。

戻り値

オブジェクトのテンプレートの GUID が格納された String 値を返す。

エラー コード

失敗した場合はエラーが発生し、Err.Number に DXFILEERR_BADVALUE が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。


DirectXFileEnum

ファイル内のデータ オブジェクトに対する処理を繰り返し、グローバル ユニーク識別子 (GUID) または名前でデータ オブジェクトを取得するには、DirectXFileEnum クラスのメソッドを使用する。

DirectXFileEnum クラスのメソッドは、以下のグループにまとめることができる。

オブジェクトの取得 | GetDataObjectById
 | GetDataObjectByName
列挙 | GetNextDataObject

DirectXFileEnum クラスのグローバル ユニーク識別子 (GUID) は IID_IDirectXFileEnumObject である。


DirectXFileEnum.GetDataObjectById

グローバル ユニーク識別子 (GUID) で指定されたデータ オブジェクトを取得する。

object.GetDataObjectById( _
    ID As String, _
    RetVal As DirectXFileData)

指定項目

object
DirectXFileEnum オブジェクトを表すオブジェクト式。
ID
オブジェクトの GUID が設定された String 値。
RetVal
返されたファイル データ オブジェクトを表す DirectXFileData オブジェクト。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

DXFILEERR_BADVALUE
DXFILEERR_NOTFOUND

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。


DirectXFileEnum.GetDataObjectByName

指定された名前を持つデータ オブジェクトを取得する。

object.GetDataObjectByName( _
    ID As String, _
    RetVal As DirectXFileData)

指定項目

object
DirectXFileEnum オブジェクトを表すオブジェクト式。
ID
オブジェクト名を保持する String 値。
RetVal
返されたファイル データ オブジェクトを表す DirectXFileData オブジェクト。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

DXFILEERR_BADVALUE
DXFILEERR_NOTFOUND

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。


DirectXFileEnum.GetNextDataObject

Microsoft® DirectX® ファイルの中にある次の最上位レベル オブジェクトを取得する。

object.GetNextDataObject() As DirectXFileData

指定項目

object
DirectXFileEnum オブジェクトを表すオブジェクト式。

戻り値

取得したファイル データ オブジェクトを表す DirectXFileData オブジェクトを返す。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

DXFILEERR_BADVALUE
DXFILEERR_NOMOREOBJECTS

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

最上位レベル オブジェクトは、常にデータ オブジェクトである。データ参照オブジェクトおよびバイナリ オブジェクトは、データ オブジェクトの子になることだけができる。


DirectXFileObject

Microsoft® DirectX® ファイル オブジェクトについての情報を取得するには、DirectXFileObject クラスのメソッドを使用する。

DirectXFileObject クラスのメソッドは、以下のグループにまとめることができる。

情報 | GetId
 | GetName

DirectXFileObject クラスのグローバル ユニーク識別子 (GUID) は IID_IDirectXFileObject である。


DirectXFileObject.GetId

Microsoft® DirectX® ファイル オブジェクトを識別するグローバル ユニーク識別子 (GUID) を取得する。

object.GetId() As String

指定項目

object
DirectXFileObject オブジェクトを表すオブジェクト式。

戻り値

オブジェクトの GUID が格納された String 値を返す。

エラー コード

失敗した場合はエラーが発生し、Err.Number に DXFILEERR_BADVALUE が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

対象

このメソッドは次のクラスに適用される。これらのクラスは、DirectXFileObject のメソッドを実装する。

  • DirectXFileBinary
  • DirectXFileData

注意

ファイルの GUID が格納された String 値が返る。


DirectXFileObject.GetName

Microsoft® DirectX® ファイル オブジェクトの名前を取得する。

object.GetName() As String

指定項目

object
DirectXFileObject オブジェクトを表すオブジェクト式。

戻り値

オブジェクトの名前が格納された String 値を返す。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

DXFILEERR_BADALLOC
DXFILEERR_BADVALUE

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

対象

このメソッドは次のクラスに適用される。これらのクラスは、DirectXFileObject のメソッドを実装する。

  • DirectXFileBinary
  • DirectXFileData


DirectXFileReference

データ参照オブジェクトをサポートするには、DirectXFileReference クラスのメソッドを使用する。データ参照オブジェクトは、ファイル内で既に定義されているデータ オブジェクトを参照している。データ参照オブジェクトを使うと、ファイル内で繰り返し定義しなくても、同じオブジェクトを繰り返し使用できる。

DirectXFileReference クラスは、次のようなグループに分類できる DirectXFileObject メソッドを実装している。

情報 | GetId
 | GetName

オブジェクトがデータ参照オブジェクトであるとわかった場合は、DirectXFileReference.Resolve メソッドを使って、ファイル内で既に定義されている参照対象オブジェクトを取得する。

データ参照オブジェクトを識別する方法については、「DirectXFileData クラス」を参照すること。

DirectXFileReference クラスのグローバル ユニーク識別子 (GUID) は IID_IDirectXFileDataReference である。


DirectXFileReference.Resolve

データ参照を解決する。

object.Resolve() As DirectXFileData

指定項目

object
DirectXFileReference オブジェクトを表すオブジェクト式。

戻り値

返されたファイル データ オブジェクトを表す DirectXFileData オブジェクト。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

DXFILEERR_BADVALUE
DXFILEERR_NOTFOUND

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。


DirectXFileSave

データ オブジェクトを作成し、テンプレートとデータ オブジェクトを保存するには、DirectXFileSave クラスのメソッドを使用する。テンプレートは、必ずしもすべてのファイルについて必要ではない。たとえば、DirectX ファイルごとにテンプレートを複製するのではなく、すべてのテンプレートを 1 つの Microsoft® DirectX® ファイルに収めてもかまわない。

DirectXFileSave クラスを取得するには、DirectXFile.CreateSaveObject メソッドを呼び出す。

DirectXFileSave クラスのメソッドは、以下のグループにまとめることができる。

生成 | CreateDataObject
保存 | SaveData
 | SaveTemplates

DirectXFileSave クラスのグローバル ユニーク識別子 (GUID) は IID_IDirectXFileSaveObject である。


DirectXFileSave.CreateDataObject

データ オブジェクトを作成する。

object.CreateDataObject( _
    TemplateGuid As String, _
    Name As String, _
    DataTypeGuid As String, _
    ByteCount As Long, _
    Data As Any) As DirectXFileData

指定項目

object
DirectXFileSave オブジェクトを表すオブジェクト式。
TemplateGuid
データ オブジェクトのテンプレートのグローバル ユニーク識別子 (GUID) を保持する String 値。
Name
オブジェクトの名前を保持する String 値。オブジェクトに名前がない場合は、空の文字列を指定する。
DataTypeGuid
データ オブジェクトの GUID を保持する String 値。オブジェクトに GUID がない場合は、空の文字列を指定する。
ByteCount
データ オブジェクトのサイズを保持する Long 値 (バイト単位)。
Data
必要な全メンバのデータを保持するバッファ。

戻り値

作成されたファイル データ オブジェクトを表す DirectXFileData オブジェクトを返す。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

DXFILEERR_BADALLOC
DXFILEERR_BADVALUE

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

注意

作成したデータ オブジェクトをデータ参照オブジェクトで参照する場合は、Name パラメータと DataTypeGuid パラメータのうち少なくともどちらか一方は、空の文字列であってはならない。

このメソッドで作成したデータを保存する前に、DirectXFileSave.SaveTemplates メソッドを使ってテンプレートを保存しなければならない。その後、DirectXFileSave.SaveData メソッドを使って、作成したデータを保存する。

オプション データを保存する必要がある場合は、このメソッドを呼び出した後、SaveData メソッドを呼び出す前に、DirectXFileData.AddDataObject メソッドを使用して行う。子オブジェクトがある場合は、SaveData を呼び出す前に追加する。

参照

DirectXFileData.AddDataObject、DirectXFileSave.SaveData、DirectXFileSave.SaveTemplates


DirectXFileSave.SaveData

データ オブジェクトとその子を Microsoft® DirectX® ファイルに保存する。

object.SaveData( _
    DataObj As DirectXFileData)

指定項目

object
DirectXFileSave オブジェクトを表すオブジェクト式。
DataObj
保存するファイル データ オブジェクトを表す DirectXFileData オブジェクト。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

DXFILEERR_BADARRAYSIZE
DXFILEERR_BADVALUE

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。


DirectXFileSave.SaveTemplates

Microsoft® DirectX® ファイルにテンプレートを保存する。

object.SaveTemplates( _
    Count As Long, _
    TemplateGuids() As String)

指定項目

object
DirectXFileSave オブジェクトを表すオブジェクト式。
Count
保存するテンプレートの総数。
TemplateGuids
保存する全テンプレートの GUID を保持する String 値の配列。

エラー コード

失敗した場合はエラーが発生し、Err.Number に DXFILEERR_BADVALUE が設定される。

エラー トラッピングの詳細については、Microsoft® Visual Basic® の「エラー処理」を参照すること。

参照

DirectXFileSave.CreateDataObject


列挙

ここでは、DirectX® ファイルで使用される以下の列挙について説明する。

  • CONST_DXFILEERR
  • CONST_DXFILEFORMATFLAGS


CONST_DXFILEERR

システムで発生するファイルのエラー コードを定義する。これらのエラー コードの詳細については、「エラー コード」を参照すること。


CONST_DXFILEFORMATFLAGS

塗りつぶしモードを記述する定数を定義する。

Enum CONST_DXFILEFORMATFLAGS
    DXFILEFORMAT_BINARY     = 0
    DXFILEFORMAT_TEXT       = 1
    DXFILEFORMAT_COMPRESSED = 2
End Enum

定数

DXFILEFORMAT_BINARY
バイナリ ファイルを示す。
DXFILEFORMAT_COMPRESSED
圧縮ファイルを示す。
DXFILEFORMAT_TEXT
テキスト ファイルを示す。

参照

D3DX8.SaveMeshToX 、 DirectXFile.CreateSaveObject


エラー コード

Microsoft® DirectX (.x) ファイルの処理に使用するメソッドからは、標準のエラー コードに加えて、次のエラー コードが返る場合がある。

DXFILE_OK
コマンドが正常に完了した。
DXFILEERR_BADALLOC
メモリの割り当てに失敗した。
DXFILEERR_BADARRAYSIZE
配列のサイズが無効である。
DXFILEERR_BADCACHEFILE
.x ファイルのデータを格納しているキャッシュ ファイルが無効である。キャッシュ ファイルには、ネットワークから取得されて、ハード ディスクにキャッシュされて、以降のリクエストにおいて取得されたデータが格納されている。
DXFILEERR_BADDATAREFERENCE
参照されているデータが無効である。
DXFILEERR_BADFILE
ファイルが無効である。
DXFILEERR_BADFILECOMPRESSIONTYPE
ファイル圧縮のタイプが無効である。
DXFILEERR_BADFILEFLOATSIZE
浮動小数点のサイズが無効である。
DXFILEERR_BADFILETYPE
ファイルが DirectX (.x) ファイルではない。
DXFILEERR_BADFILEVERSION
ファイルのバージョンが無効である。
DXFILEERR_BADINTRINSICS
固有情報が無効である。
DXFILEERR_BADOBJECT
オブジェクトが無効である。
DXFILEERR_BADRESOURCE
リソースが無効である。
DXFILEERR_BADTYPE
オブジェクト タイプが無効である。
DXFILEERR_BADVALUE
パラメータが無効である。
DXFILEERR_FILENOTFOUND
ファイルが見つからない。
DXFILEERR_INTERNALERROR
内部エラーが発生した。
DXFILEERR_NOINTERNET
インターネット接続が見つからない。
DXFILEERR_NOMOREDATA
それ以上利用できるデータがない。
DXFILEERR_NOMOREOBJECTS
すべてのオブジェクトが列挙されている。
DXFILEERR_NOMORESTREAMHANDLES
ストリーム ハンドルが利用できない。
DXFILEERR_NOTDONEYET
処理が完了していない。
DXFILEERR_NOTFOUND
オブジェクトが見つからない。
DXFILEERR_PARSEERROR
ファイルを解析できない。
DXFILEERR_RESOURCENOTFOUND
リソースが見つからない。
DXFILEERR_NOTEMPLATE
テンプレートを利用できない。
DXFILEERR_URLNOTFOUND
URL が見つからない。


X ファイル フォーマット リファレンス

ここでは、Microsoft® DirectX® (.x) ファイル フォーマットのリファレンス情報を記述する。

  • X ファイル テンプレート
  • バイナリ フォーマット


X ファイル テンプレート

ここでは、次の .x ファイル テンプレートについて詳しく説明する。

  • Header
  • Vector
  • Coords2d
  • Quaternion
  • Matrix4x4
  • ColorRGBA
  • ColorRGB
  • IndexedColor
  • Boolean
  • Boolean2d
  • Material
  • TextureFilename
  • MeshFace
  • MeshFaceWraps
  • MeshTextureCoords
  • MeshNormals
  • MeshVertexColors
  • MeshMaterialList
  • Mesh
  • FrameTransformMatrix
  • Frame
  • FloatKeys
  • TimedFloatKeys
  • AnimationKey
  • AnimationOptions
  • Animation
  • AnimationSet
  • Patch
  • PatchMesh
  • VertexDuplicationIndices
  • XSkinMeshHeader
  • SkinWeights


Header

アプリケーション固有のヘッダーを定義する。

UUID

<3D82AB43-62DA-11cf-AB39-0020AF71E433>

メンバ名 | 型 | オプションの配列サイズ | オプションのデータ オブジェクト
major | WORD |  | なし
minor | WORD |  |
flags | DWORD


Vector

ベクトルを定義する。

UUID

<3D82AB5E-62DA-11cf-AB39-0020AF71E433>

メンバ名 | 型 | オプションの配列サイズ | オプションのデータ オブジェクト
x | FLOAT |  | なし
y | FLOAT |  |
z | FLOAT


Coords2d

メッシュのテクスチャ座標を定義するために使用する 2 次元ベクトル。

UUID

<F6F23F44-7686-11cf-8F52-0040333594A3>

メンバ名 | 型 | オプションの配列サイズ | オプションのデータ オブジェクト
u | FLOAT |  | なし
v | FLOAT |  |


Quaternion

現在は使用されていない。

UUID

<10DD46A3-775B-11cf-8F52-0040333594A3>

メンバ名 | 型 | オプションの配列サイズ | オプションのデータ オブジェクト
s | FLOAT |  | なし
v | Vector |  |


Matrix4x4

4 × 4 の行列を定義する。これはフレーム トランスフォーム行列として使用される。

UUID

<F6F23F45-7686-11cf-8F52-0040333594A3>

メンバ名 | 型 | オプションの配列サイズ | オプションのデータ オブジェクト
matrix | 配列 FLOAT | 16 | なし


ColorRGBA

アルファ成分を使って色オブジェクトを定義する。これは、マテリアル テンプレート定義で表面の色として使用される。

UUID

<35FF44E0-6C7C-11cf-8F52-0040333594A3>

メンバ名 | 型 | オプションの配列サイズ | オプションのデータ オブジェクト
red | FLOAT |  | なし
green | FLOAT |  |
blue | FLOAT
alpha | FLOAT


ColorRGB

基本的な RGB 色オブジェクトを定義する。

UUID

<D3E16E81-7835-11cf-8F52-0040333594A3>

メンバ名 | 型 | オプションの配列サイズ | オプションのデータ オブジェクト
red | FLOAT |  | なし
green | FLOAT |  |
blue | FLOAT


IndexedColor

インデックス パラメータと RGBA 色で構成され、メッシュ頂点カラーを定義するために使用される。インデックスは色を適用する頂点を定義する。

UUID

<1630B820-7842-11cf-8F52-0040333594A3>

メンバ名 | 型 | オプションの配列サイズ
index | DWORD |
indexColor | ColorRGBA


Boolean

単純なブール型を定義する。このテンプレートは 0 または 1 に設定しなければならない。

UUID

<4885AE61-78E8-11cf-8F52-0040333594A3>

メンバ名 | 型 | オプションの配列サイズ | オプションのデータ オブジェクト
truefalse | DWORD |  | なし


Boolean2d

MeshFaceWraps テンプレートで、個々の面のテクスチャ トポロジを定義するために使用される 2 つのブール値のセットを定義する。

UUID

<4885AE63-78E8-11cf-8F52-0040333594A3>

メンバ名 | 型 | オプションの配列サイズ | オプションのデータ オブジェクト
u | Boolean |  | なし
v | Boolean |  |


Material

メッシュ全体またはメッシュの個々の面のいずれかに適用できる基本的なマテリアル色を定義する。累乗はマテリアルのスペキュラ指数である。アンビエント色にはアルファ成分が必要であることに注意すること。

TextureFilename は、オプションのデータ オブジェクトである。このオブジェクトが存在しない場合、面はテクスチャ処理されない。

UUID

<3D82AB4D-62DA-11cf-AB39-0020AF71E433>

メンバ名 | 型 | オプションの配列サイズ | オプションのデータ オブジェクト
faceColor | ColorRGBA |  | 任意
power | FLOAT |  |
specularColor | ColorRGB
emissiveColor | ColorRGB


TextureFilename

メッシュまたは面に適用するテクスチャのファイル名を指定できるようにする。このテンプレートは、マテリアル オブジェクト内に存在していなければならない。

UUID

<A42790E1-7810-11cf-8F52-0040333594A3>

メンバ名 | 型 | オプションの配列サイズ | オプションのデータ オブジェクト
filename | STRING |  | なし


MeshFace

Mesh テンプレートで、メッシュの面を定義するために使用される。nFaceVertexIndices 配列の各要素は、面を構築するために使用されるメッシュ頂点を参照する。

UUID

<3D82AB5F-62DA-11cf-AB39-0020AF71E433>

メンバ名 | 型 | オプションの配列サイズ | オプションのデータ オブジェクト
nFaceVertexIndices | DWORD |  | なし
faceVertexIndices | 配列 DWORD | nFaceVertexIndicies |


MeshFaceWraps

ラップ内の各面のテクスチャ トポロジを定義するために使用される。nFaceWrapValues メンバの値は、メッシュの面の数と同じでなければならない。

UUID

<4885AE62-78E8-11cf-8F52-0040333594A3>

メンバ名 | 型 | オプションの配列サイズ | オプションのデータ オブジェクト
nFaceWrapValues | DWORD |  | なし
faceWrapValues | Boolean2d |  |


MeshTextureCoords

メッシュのテクスチャ座標を定義する。

UUID

<F6F23F40-7686-11cf-8F52-0040333594A3>

メンバ名 | 型 | オプションの配列サイズ | オプションのデータ オブジェクト
nTextureCoords | DWORD |  | なし
textureCoords | 配列 Coords2d | nTextureCoords |


MeshNormals

メッシュの法線を定義する。ベクトルの最初の配列は法線ベクトル自体であり、2 番目の配列は特定の面に適用すべき法線を指定するインデックスの配列である。nFaceNormals メンバの値は、メッシュの面の数と同じでなければならない。

UUID

<F6F23F43-7686-11cf-8F52-0040333594A3>

メンバ名 | 型 | オプションの配列サイズ | オプションのデータ オブジェクト
nNormals | DWORD |  | なし
normals | 配列 Vector | nNormals |
nFaceNormals | DWORD |
faceNormals | 配列 MeshFace | nFaceNormals


MeshVertexColors

面ごと、またはメッシュごとにマテリアルを適用する代わりに、メッシュの頂点カラーを指定する。

UUID

<1630B821-7842-11cf-8F52-0040333594A3>

メンバ名 | 型 | オプションの配列サイズ | オプションのデータ オブジェクト
nVertexColors | DWORD |  | なし
vertexColors | 配列 IndexedColor | nVertexColors |


MeshMaterialList

メッシュ オブジェクトで、どのマテリアルをどの面に適用するかを指定するために使用される。nMaterials メンバは存在するマテリアルの数を指定し、materials は適用するマテリアルを指定する。

UUID

<F6F23F42-7686-11cf-8F52-0040333594A3>

メンバ名 | 型 | オプションの配列サイズ | オプションのデータ オブジェクト
nMaterials | DWORD |  | Material
nFaceIndexes | DWORD |  |
FaceIndexes | 配列 DWORD | nFaceIndexes


Mesh

単純なメッシュを定義する。最初の配列は頂点のリストで、2 番目の配列は頂点配列にインデックス付けすることによってメッシュの面を定義する。

UUID

<3D82AB44-62DA-11cf-AB39-0020AF71E433>

メンバ名 | 型 | オプションの配列サイズ | オプションのデータ オブジェクト
nVertices | DWORD |  | 任意
vertices | 配列 Vector | nVertices |
nFaces | DWORD |
faces | 配列 MeshFace | nFaces

オプションのデータ要素

次のオプションのデータ要素を使用できる。

Data element | 説明
MeshFaceWraps | この要素が存在しない場合、u および v の両方のラッピングのデフォルトは FALSE になる。
MeshTextureCoords | この要素が存在しない場合、テクスチャ座標は存在しない。
MeshNormals | この要素が存在しない場合、法線は API の GenerateNormals メソッドを使って生成される。
MeshVertexColors | この要素が存在しない場合、色のデフォルトは白になる。
MeshMaterialList | この要素が存在しない場合、マテリアルのデフォルトは白になる。


FrameTransformMatrix

フレーム (およびそのすべての子オブジェクト) のローカル トランスフォームを定義する。

UUID

<F6F23F41-7686-11cf-8F52-0040333594A3>

メンバ名 | 型 | オプションの配列サイズ | オプションのデータ オブジェクト
frameMatrix | Matrix4x4 |  | なし


Frame

フレームを定義する。現在、フレームには Mesh および FrameTransformMatrix 型のオブジェクトを含めることができる。

UUID

<3D82AB46-62DA-11cf-AB39-0020AF71E433>

メンバ名 | 型 | オプションの配列サイズ | オプションのデータ オブジェクト
なし |  |  | 任意

オプションのデータ要素

次のオプションの要素を使用できる。

Data element | 説明
FrameTransformMatrix | この要素が存在しない場合、フレームにローカル トランスフォームが適用されない。
Mesh | フレームの子になる任意の数のメッシュ オブジェクト。これらのオブジェクトは、インラインで、または参照によって指定できる。


FloatKeys

浮動小数点数 (float) の配列および配列内の float の数を定義する。これは、アニメーション キーのセットを定義するために使用される。

UUID

<10DD46A9-775B-11cf-8F52-0040333594A3>

メンバ名 | 型 | オプションの配列サイズ | オプションのデータ オブジェクト
nValues | DWORD |  | なし
values | 配列 FLOAT | nValues |


TimedFloatKeys

アニメーションで使用される浮動小数点数のセットおよび正の時間を定義する。

UUID

<F406B180-7B3B-11cf-8F52-0040333594A3>

メンバ名 | 型 | オプションの配列サイズ | オプションのデータ オブジェクト
time | DWORD |  | なし
tfkeys | FloatKeys |  |


AnimationKey

アニメーション キーのセットを定義する。keyType メンバは、キーが回転、スケーリング、位置、または行列キーのいずれであるかを指定する (それぞれ、整数 0、1、2、3 を使用する)。行列キーは、アニメーション データのセットをトランスフォーム行列として表す必要がある場合に便利である。

UUID

<10DD46A8-775B-11cf-8F52-0040333594A3>

メンバ名 | 型 | オプションの配列サイズ | オプションのデータ オブジェクト
keyType | DWORD |  | なし
nKeys | DWORD |  |
keys | 配列 TimedFloatKeys | nKeys


AnimationOptions

アニメーション オプションを設定できるようにする。openclosed メンバは閉じたアニメーションを示す 0、または開いたアニメーションを示す 1 のいずれかに設定できる。positionquality メンバは、指定された位置キーの位置の品質を設定するために使用される。スプライン位置を示す 0、またはリニア位置を示す 1 のいずれかに設定できる。デフォルトでは、アニメーションは閉じられる。

UUID

<E2BF56C0-840F-11cf-8F52-0040333594A3>

メンバ名 | 型 | オプションの配列サイズ | オプションのデータ オブジェクト
openclosed | DWORD |  | なし
positionquality | DWORD |  |


Animation

前のフレームを参照するアニメーションを格納する。フレームへの参照が 1 つと、少なくとも 1 セットの AnimationKey テンプレートが格納されている必要がある。AnimationOptions データ オブジェクトを格納することもできる。

UUID

<3D82AB4F-62DA-11cf-AB39-0020AF71E433>

メンバ名 | 型 | オプションの配列サイズ | オプションのデータ オブジェクト
なし |  |  | 任意

オプションのデータ要素

次のオプションのデータ要素が使用される。

Data element | 説明
AnimationKey | すべてのアニメーションで AnimationKeys が必要とされる。
AnimationOptions | この要素が存在しない場合、アニメーションは閉じられる。


AnimationSet

1 つ以上の Animation オブジェクトを格納する。アニメーション セット内の各アニメーションは、どの時点でも同じ時間を持つ。アニメーション セットの時間を増やすと、含まれているすべてのアニメーションの時間が増加する。

UUID

<3D82AB50-62DA-11cf-AB39-0020AF71E433>

メンバ名 | 型 | オプションの配列サイズ | オプションのデータ オブジェクト
なし |  |  | Animation


Patch

ベジェ制御パッチを定義する。この配列はパッチの制御点を定義する。

UUID

<A3EB5D44-FC22-429D-9AFB-3221CB9719A6>

メンバ名 | 型 | オプションの配列サイズ | オプションのデータ オブジェクト
nControlIndices | DWORD |  | なし
controlIndices | 配列 DWORD | nControlIndices |

パッチのタイプは、次の表に示されているように、制御点の数によって定義される。

制御点の数 | 型
10 | 3 次ベジェ三角形パッチ
15 | 4 次ベジェ三角形パッチ
16 | 3 次ベジェ四角形 (矩形) パッチ

制御点の次数は、三角形パッチおよび矩形パッチについて次の図に示されているように、らせん形のパターンで示される。

三角形パッチでは次のパターンを使用していた。

矩形パッチでは次のパターンを使用する。


PatchMesh

ベジェ パッチによって定義されたメッシュを定義する。最初の配列は頂点のリストで、2 番目の配列は頂点配列にインデックス付けすることによってメッシュのパッチを定義する。

UUID

<D02C95CC-EDBA-4305-9B5D-1820D7704BBF>

メンバ名 | 型 | オプションの配列サイズ | オプションのデータ オブジェクト
nVertices | DWORD |  | なし
vertices | 配列 Vector | nVertices |
nPatches | DWORD |
patches | 配列 Patch | nPatches

パッチは、各パッチの制御点として、頂点の配列内の頂点を使用する。


VertexDuplicationIndices

このテンプレートはメッシュごとにインスタンス化され、メッシュ内のどの頂点が互いに重複しているかという情報を保持する。頂点がスムージング グループまたはマテリアルの境界にある場合に重複が発生する。このテンプレートの目的は、周辺パラメータが異なるどの頂点が、実際にはモデル内の同じ頂点であるかを、ローダーが決定できるようにすることである。特定の用途 (メッシュの単純化など) で、この情報を利用できる。

UUID

<B8D65549-D7C9-4995-89CF-53A9A8B031E3>

メンバ名 | 型 | オプションの配列サイズ | オプションのデータ オブジェクト
nIndices | DWORD |  | なし
nOriginalVertices | DWORD |  |
indices | 配列 DWORD | nIndices

重複が発生する前のメッシュ内の頂点の数は nOriginalVertices である。値 indices[n] は、重複が発生しない場合にメッシュの頂点配列内の vertex[n] が持つ頂点インデックスを保持する。したがって、この配列内のインデックスが同じである場合は、重複した頂点であることを示す。


XSkinMeshHeader

このテンプレートは、エクスポートされたスキニング情報を含むメッシュ内でのみ、メッシュごとにインスタンス化される。このテンプレートの目的は、エクスポートされたスキニング情報の性質に関する情報を提供することである。

UUID

<3CF169CE-FF7C-44ab-93C0-F78F62D172E2>

メンバ名 | 型 | オプションの配列サイズ | オプションのデータ オブジェクト
nMaxSkinWeightsPerVertex | WORD |  | なし
nMaxSkinWeightsPerFace | WORD |  |
nBones | WORD

メッシュ内の頂点に影響するトランスフォームの最大数は nMaxSkinWeightsPerVertex である。任意の面の 3 つの頂点に影響する一意のトランスフォームの最大数は nMaxSkinWeightsPerFace である。このメッシュの頂点に影響するボーンの数は nBones である。


SkinWeights

このテンプレートはメッシュごとにインスタンス化される。メッシュ内に、このテンプレートの n 個のインスタンスのシーケンスが表示される。ここで、n はメッシュ内の頂点に影響するボーンの数 (X ファイル フォーマット) である。テンプレートの各インスタンスは、基本的に特定のボーンのメッシュへの影響を定義する。頂点インデックスのリスト、および対応する重みのリストがある。

UUID

<6F0D123B-BAD2-4167-A0D0-80224F25FABB>

メンバ名 | 型 | オプションの配列サイズ | オプションのデータ オブジェクト
transformNodeName | STRING |  | なし
nWeights | DWORD |  |
vertexIndices | 配列 DWORD | nWeights
weights | 配列 float | nWeights
matrixOffset | Matrix4x4 |

影響を定義するボーンの名前は transformNodeName であり、nWeights はこのボーンの影響を受ける頂点の数である。このボーンの影響を受ける頂点は vertexIndices に格納されており、このボーンの影響を受ける各頂点の重みは weights に格納される。

行列 matrixOffset は、メッシュの頂点をボーンの空間にトランスフォームする。ボーンのトランスフォームと連結すると、ボーンの影響を受けるメッシュのワールド空間座標が得られる。


バイナリ フォーマット

ここでは、DirectX 3.0 のリリース以降導入された Microsoft® DirectX® (.x) ファイル フォーマットのバイナリ バージョンについて詳しく説明する。ここで説明されている内容は、「X ファイル アーキテクチャ」の説明を参照しながら読むことを推奨する。

バイナリ フォーマットは、トークン化されたテキスト フォーマットの表現である。トークンは、スタンドアロンである場合と、プリミティブ データ レコードが付属する場合がある。スタンドアロン トークンは文法的な構造を提供し、レコード生成トークンは必要なデータを提供する。

すべてのデータはリトル エンディアン フォーマットで格納されることに注意すること。有効なバイナリ データ ストリームは、ヘッダーと、それに続くテンプレートとデータ オブジェクトの両方またはいずれかで構成される。

ここでは、バイナリ ファイル フォーマットの次のコンポーネントについて説明し、テンプレートおよびバイナリ データ オブジェクトの例を示す。

  • ヘッダー
  • トークン
  • トークン レコード
  • テンプレート
  • データ
  • 例


ヘッダー

バイナリ ヘッダーを直接読み書きする場合は、次の定義を使用しなければならない。圧縮データ ストリームは現在サポートされていないので、ここでは詳しく示されていないことに注意すること。

#define XOFFILE_FORMAT_MAGIC \
  ((long)'x' + ((long)'o' << 8) + ((long)'f' << 16) + ((long)' ' << 24))

#define XOFFILE_FORMAT_VERSION \
  ((long)'0' + ((long)'3' << 8) + ((long)'0' << 16) + ((long)'2' << 24))

#define XOFFILE_FORMAT_BINARY \
  ((long)'b' + ((long)'i' << 8) + ((long)'n' << 16) + ((long)' ' << 24))

#define XOFFILE_FORMAT_TEXT   \
  ((long)'t' + ((long)'x' << 8) + ((long)'t' << 16) + ((long)' ' << 24))

#define XOFFILE_FORMAT_COMPRESSED \
  ((long)'c' + ((long)'m' << 8) + ((long)'p' << 16) + ((long)' ' << 24))

#define XOFFILE_FORMAT_FLOAT_BITS_32 \
  ((long)'0' + ((long)'0' << 8) + ((long)'3' << 16) + ((long)'2' << 24))

#define XOFFILE_FORMAT_FLOAT_BITS_64 \
  ((long)'0' + ((long)'0' << 8) + ((long)'6' << 16) + ((long)'4' << 24))


トークン

トークンはリトル エンディアン WORD として記述される。以下のトークンのリストは、レコード生成トークンとスタンドアロン トークンに分かれている。

レコード生成トークンは次のように定義される。

#define TOKEN_NAME 1
#define TOKEN_STRING 2
#define TOKEN_INTEGER 3
#define TOKEN_GUID 5
#define TOKEN_INTEGER_LIST 6
#define TOKEN_FLOAT_LIST 7

スタンドアロン トークンは次のように定義される。

#define TOKEN_OBRACE 10
#define TOKEN_CBRACE 11
#define TOKEN_OPAREN 12
#define TOKEN_CPAREN 13
#define TOKEN_OBRACKET 14
#define TOKEN_CBRACKET 15
#define TOKEN_OANGLE 16
#define TOKEN_CANGLE 17
#define TOKEN_DOT 18
#define TOKEN_COMMA 19
#define TOKEN_SEMICOLON 20
#define TOKEN_TEMPLATE 31
#define TOKEN_WORD 40
#define TOKEN_DWORD 41
#define TOKEN_FLOAT 42
#define TOKEN_DOUBLE 43
#define TOKEN_CHAR 44
#define TOKEN_UCHAR 45
#define TOKEN_SWORD 46
#define TOKEN_SDWORD 47
#define TOKEN_VOID 48
#define TOKEN_LPSTR 49
#define TOKEN_UNICODE 50
#define TOKEN_CSTRING 51
#define TOKEN_ARRAY 52


トークン レコード

ここでは、各レコード生成トークンのレコードのフォーマットについて説明する。説明するトピックは、次のとおりである。

  • TOKEN_NAME
  • TOKEN_STRING
  • TOKEN_INTEGER
  • TOKEN_GUID
  • TOKEN_INTEGER_LIST
  • TOKEN_FLOAT_LIST


TOKEN_NAME

可変長レコード。トークンの後には、name フィールドに続くバイト数を指定する count 値が続く。長さ count の ASCII 名でレコードが完了する。

フィールド | 型 | サイズ (バイト) | 内容
token | WORD | 2 | TOKEN_NAME
count | DWORD | 4 | バイト単位の name フィールドの長さ
name | BYTE 配列 | count | ASCII 名


TOKEN_STRING

可変長レコード。トークンの後には、string フィールドに続くバイト数を指定する count 値が続く。長さ count の ASCII 文字列ではレコードは継続し、終了トークンによって完了する。terminator の選択は、ほかで説明する構文の問題によって決まる。

フィールド | 型 | サイズ (バイト) | 内容
token | WORD | 2 | TOKEN_STRING
count | DWORD | 4 | バイト単位の string フィールドの長さ
string | BYTE 配列 | count | ASCII 文字列
terminator | DWORD | 4 | TOKEN_SEMICOLON または TOKEN_COMMA


TOKEN_INTEGER

固定長レコード。トークンの後には、必要な整数値が続く。

フィールド | 型 | サイズ (バイト) | 内容
token | WORD | 2 | TOKEN_INTEGER
value | DWORD | 4 | 単一の整数


TOKEN_GUID

固定長レコード。トークンの後には、OSF DCE 標準で定義されている 4 つのデータ フィールドが続く。

フィールド | 型 | サイズ (バイト) | 内容
token | WORD | 2 | TOKEN_GUID
data1 | DWORD | 4 | UUID データ フィールド 1
data2 | WORD | 2 | UUID データ フィールド 2
data3 | WORD | 2 | UUID データ フィールド 3
data4 | BYTE 配列 | 8 | UUID データ フィールド 4


TOKEN_INTEGER_LIST

可変長レコード。トークンの後には、list フィールドに続く整数の数を指定する count 値が続く。効率化のために、連続する整数のリストは単一のリストに合成することが望ましい。

フィールド | 型 | サイズ (バイト) | 内容
token | WORD | 2 | TOKEN_INTEGER_LIST
count | DWORD | 4 | list フィールドの整数の数
list | DWORD | 4 × count | 整数のリスト


TOKEN_FLOAT_LIST

可変長レコード。トークンの後には、list フィールドに続く浮動小数点数または倍精度整数の数を指定する count 値が続く。浮動小数点数値 (float または double) のサイズは、ファイル ヘッダーで指定された float のサイズの値によって決まる。効率化のために、連続する TOKEN_FLOAT_LIST は単一のリストに合成することが望ましい。

フィールド | 型 | サイズ (バイト) | 内容
token | WORD | 2 | TOKEN_FLOAT_LIST
count | DWORD | 4 | list フィールドの浮動小数点数または倍精度整数の数
list | float/double 配列 | 4 または 8 ﾗ count | float または double のリスト


テンプレート

テンプレートには、次の構文の定義がある。

template              : TOKEN_TEMPLATE name TOKEN_OBRACE
                            class_id
                            template_parts
                            TOKEN_CBRACE

template_parts        : template_members_part TOKEN_OBRACKET
                        template_option_info
                        TOKEN_CBRACKET
                      | template_members_list

template_members_part :/* 空 */
                      | template_members_list

template_option_info  : ellipsis
                      | template_option_list

template_members_list :    template_members
                      | template_members_list template_members

template_members      : primitive
                      | array
                      | template_reference

primitive             : primitive_type optional_name TOKEN_SEMICOLON

array                 : TOKEN_ARRAY array_data_type name dimension_list
                        TOKEN_SEMICOLON

template_reference    : name optional_name YT_SEMICOLON

primitive_type        : TOKEN_WORD
                      | TOKEN_DWORD
                      | TOKEN_FLOAT
                      | TOKEN_DOUBLE
                      | TOKEN_CHAR
                      | TOKEN_UCHAR
                      | TOKEN_SWORD
                      | TOKEN_SDWORD
                      | TOKEN_LPSTR
                      | TOKEN_UNICODE
                      | TOKEN_CSTRING

array_data_type       : primitive_type
                      | name

dimension_list        : dimension
                      | dimension_list dimension

dimension             : TOKEN_OBRACKET dimension_size TOKEN_CBRACKET

dimension_size        : TOKEN_INTEGER
                      | name

template_option_list  : template_option_part
                      | template_option_list template_option_part

template_option_part  : name optional_class_id

name                  : TOKEN_NAME

optional_name         :/* 空 */
                      | name

class_id              : TOKEN_GUID

optional_class_id     :/* 空 */
                      | class_id

ellipsis              : TOKEN_DOT TOKEN_DOT TOKEN_DOT


データ

データ オブジェクトには、次の構文の定義がある。

object                : identifier optional_name TOKEN_OBRACE
                            optional_class_id
                            data_parts_list
                            TOKEN_CBRACE
data_parts_list       : data_part
                      | data_parts_list data_part

data_part             : data_reference
                      | object
                      | number_list
                      | float_list
                      | string_list

number_list           : TOKEN_INTEGER_LIST

float_list            : TOKEN_FLOAT_LIST

string_list           : string_list_1 list_separator

string_list_1         : string
                      | string_list_1 list_separator string

list_separator        : comma
                      | semicolon

string                : TOKEN_STRING

identifier            : name
                      | primitive_type

data_reference        : TOKEN_OBRACE name optional_class_id TOKEN_CBRACE

バイナリ ファイルの number_list および float_list データでは、TOKEN_COMMA および TOKEN_SEMICOLON は使用されないことに注意すること。カンマおよびセミコロンは string_list データで使用される。オプションのデータ メンバとして使用できるのは data_reference だけであることにも注意すること。


例

2 つのバイナリ テンプレート定義の例およびバイナリ データ オブジェクトの例を以下に示す。データはリトル エンディアン フォーマットで格納されるが、これらの例には示されていないことに注意すること。

閉じたテンプレート RGB は UUID {55b6d780-37ec-11d0-ab39-0020af71e433} によって識別され、それぞれ float 型の 3 つのメンバ r、g、b を持つ。

TOKEN_TEMPLATE, TOKEN_NAME, 3, 'R', 'G', 'B', TOKEN_OBRACE,
TOKEN_GUID, 55b6d780, 37ec, 11d0, ab, 39, 00, 20, af, 71, e4, 33,
TOKEN_FLOAT, TOKEN_NAME, 1, 'r', TOKEN_SEMICOLON,
TOKEN_FLOAT, TOKEN_NAME, 1, 'g', TOKEN_SEMICOLON,
TOKEN_FLOAT, TOKEN_NAME, 1, 'b', TOKEN_SEMICOLON,
TOKEN_CBRACE

閉じたテンプレート Matrix4x4 は UUID {55b6d781-37ec-11d0-ab39-0020af71e433} によって識別され、float 型の matrix という名前の 2 次元配列である 1 つのメンバを持つ。

TOKEN_TEMPLATE, TOKEN_NAME, 9, 'M', 'a', 't', 'r', 'i', 'x', '4', 'x', '4', TOKEN_OBRACE,
TOKEN_GUID, 55b6d781, 37ec, 11d0, ab, 39, 00, 20, af, 71, e4, 33,
TOKEN_ARRAY, TOKEN_FLOAT, TOKEN_NAME, 6, 'm', 'a', 't', 'r', 'i', 'x',
TOKEN_OBRACKET, TOKEN_INTEGER, 4, TOKEN_CBRACKET,
TOKEN_OBRACKET, TOKEN_INTEGER, 4, TOKEN_CBRACKET,
TOKEN_CBRACE

次のバイナリ データ オブジェクトは、以前に定義した RGB テンプレートのインスタンスを示している。この例のオブジェクトは blue という名前で、その 3 つのメンバ r、g、b の値はそれぞれ 0.0、0.0、1.0 である。データはリトル エンディアン フォーマットで格納されるが、この例には示されていないことに注意すること。

TOKEN_NAME, 3, 'R', 'G', 'B', TOKEN_NAME, 4, 'b', 'l', 'u', 'e', TOKEN_OBRACE,
TOKEN_FLOAT_LIST, 3, 0.0, 0.0, 1.0, TOKEN_CBRACE


DirectX Audio

ここでは、Microsoft® DirectX® を使って、アプリケーションでサウンドを再生およびキャプチャする方法について説明する。

DirectX のほかのコンポーネントと同様に、DirectX Audio は C、C++、および Microsoft® Visual Basic® で使用できる。このヘルプ ファイルでは、Visual Basic について説明する。

注 DirectX ヘルプの C++ バージョンおよび Visual Basic バージョンは、共通のソース マテリアルに基づき、目次も共通である。したがって、目次のトピックによっては、Visual Basic に関する情報が含まれないこともある。

DirectX Audio のヘルプの構成については、「ロードマップ」を参照すること。


ロードマップ

DirectX Audio については、以下のトピックで説明する。

  • DirectX Audio の新機能。DirectX 8.0 のこのコンポーネントの新機能。これまでに Microsoft® DirectSound® または Microsoft® DirectMusic® を使用した経験がある場合は、DirectX 7.0 から多くの変更が行われているため、このセクションを最初に読むこと。
  • DirectX Audio の概要。DirectX Audio の概要およびアプリケーションで使用可能な機能、オーディオの再生に関連する重要なオブジェクトと手順を示す。
  • DirectX Audio について。基本的なメカニズムについて詳しく説明する。ここでは、アプリケーションでオーディオ再生およびキャプチャを実装する方法は説明しないが、アプリケーション プログラミング インターフェイス (API) の理解に役立つはずである。
  • DirectX Audio の使い方。API の使い方のガイドである。このトピックの目次を参考にして、特定の情報が必要になったときに対象となる箇所を参照できる。このトピックは、リファレンス トピックと組み合わせて使用すること。
  • DirectX Audio の高度なトピック。主に、特殊なアプリケーションまたはパフォーマンスを高度に最適化する必要のあるアプリケーションについて説明する。
  • プログラミングのヒントおよびツール。DirectX Audio アプリケーションのコンパイルおよびデバッグに関するさまざまな情報を提供する。
  • DirectX Audio Visual Basic チュートリアル。基本的な機能を段階的に実装するチュートリアルである。実践的に DirectX Audio を理解することができる。
  • DirectX Audio Visual Basic サンプル。必要なサンプル コードを見つけるための、SDK のサンプル アプリケーションについてのガイド。基本的機能の実装方法を説明し、DirectX Audio の特定の機能を利用したサンプルを示す。
  • DirectMusic Visual Basic リファレンス。DirectX for Visual Basic タイプ ライブラリに含まれる DirectMusic API 要素について詳しく説明する。
  • DirectSound Visual Basic リファレンス。DirectX for Visual Basic タイプ ライブラリに含まれる DirectSound API 要素について詳しく説明する。

DirectMusic Producer

DirectMusic Producer は、DirectX SDK に含まれている強力なオーサリング アプリケーションである。このアプリケーションを使用して、作曲者はアプリケーションに組み込むことができるダイナミックなミュージック要素を作成できる。

アプリケーション開発よりもサウンドのデザインに重点を置いている場合は、このアプリケーションと共にインストールされる DirectMusic Producer ヘルプを参照すること。

アプリケーションを開発する場合に、対象となるマテリアルの概要ついて知りたい場合は、「アレンジ用のミュージック要素」を参照すること。


DirectX Audio の新機能

DirectX のオーディオ コンポーネントは大幅に改訂されている。さまざまなサウンドを再生するために、DirectMusic と DirectSound の API の統一が進められ、多くの新機能が追加された。

次の一覧は、主な新機能を示している。

1 つの再生メカニズムでウェーブベースとメッセージベースのサウンドを統合
ウェーブ ファイルおよびリソースを DirectMusic ローダーでロードし、DirectMusic パフォーマンスによって再生できる。アプリケーションで、ウェーブ サウンドを解析およびコピーしたり、DirectSound バッファにストリーミングする必要がなくなった。ウェーブ再生のタイミングは DirectMusic マスタ クロックに基づいており、ウェーブを音楽イベントに同期させたり、ほかのセグメントと同様にツールで処理することができる。

DirectSound API も引き続きサポートされており、DirectSound バッファを使って直接ウェーブを再生することもできる。DirectSound は、ウェーブ キャプチャおよび全二重の API である。

柔軟性を増して強化されたオーディオパス モデル
以前のバージョンの DirectMusic では、パフォーマンス チャンネルはポートにマップされ、各ポートがその出力を単一の DirectSound バッファに送信していた。新しいモデルでは、セグメントのチャンネルは、パフォーマンスから最終的な出力へのデータ フローを制御するオーディオパスにマップされる。シンセサイザからの出力を、3D ポジショニングおよびエフェクトが個別に設定されている複数の再生バッファに送信できる。オーディオパスは、アプリケーションによって動的に作成したり、セグメントにオーサリングすることができる。

DirectMusic を使った DirectX for Visual Basic アプリケーションには、オーディオパス モデルを使用する必要がある。このバージョンは、ポートへの直接アクセスをサポートしていない。

ここのセグメント状態の制御
セグメントの各再生インスタンスはそれぞれオーディオパスを持つことができ、ボリューム、パン、ピッチ ベンドなどのパラメータを、各セグメント状態について個々に変更できる。
DLS2 に基づく合成
DirectMusic シンセサイザは Downloadable Sounds (DLS) Level 2 規格に基づき、高品質なサウンド合成を可能にしている。DLS2 シンセサイザの新機能には、6 段階のエンベロープ、ボイスのレイヤリング、ウェーブフォームの解放、および追加の低周波数発振器 (LFO) などがある。各ボイスには、オプションのローパス共振フィルタがある。
特殊効果
DirectX Media Object をサウンド バッファにアタッチして、エフェクトを追加することができる。ミュージック リバーブ、I3DL2 (Interactive 3-D Audio Level 2) 環境リバーブ、ディストーション、エコーなどの DirectX Audio に用意されている標準的なエフェクトのほかに、サードパーティのエフェクトを追加できる。
キューの詳細な制御
作曲者がセグメント内にセグメントの再生を開始するポイントを設定し、セグメントが拍子記号との関係を維持できるようにすることができる。プライマリ セグメントには、ほかのセグメントにキューを与える任意のポイントを含めることができ、最も近い小節、拍、またはグリッドにキューを与える場合に比べて細かい制御が可能である。新しいセグメント キュー フラグ DMUS_SEGF_SEGMENTEND によって、現在のプライマリ セグメントの再生が終了したときに、セグメントを再生することができる。
演奏がもうすぐ終了することを知らせる通知
パフォーマンス通知イベントに新しい通知タイプ DMUS_NOTIFICATION_MUSICALMOSTEND が追加された。これは、キュー内の最後のプライマリ セグメントの終わりが近いことを示す。この通知によって、アプリケーションは新しいセグメントをスケジュールすることができる。
MIDI コントローラ サポートの強化
カーブメッセージが、RPN/NRPN コントローラの変更をサポートするようになった。
セグメントの無限回の繰り返し
新しい DMUS_SEG_REPEAT_INFINITE フラグによって、セグメントを無限に再生できる。
バンドのダウンロードおよびアンロードの簡易化
簡単なメソッド呼び出しで、バンドをセグメント オブジェクトにダウンロードしたり、セグメント オブジェクトからアンロードすることができる。
トラック データの動的生成
新しいトラック構成および再生フラグによって、セグメントを再生またはループするたびに、トラックを再生成することができる。たとえば、セグメントを再生するたびに新しいコード進行が設定されるようにコードマップ トラックを構成できる。


DirectX Audio の概要

  • DirectX Audio の機能
  • DirectX Audio 入門


DirectX Audio の機能

DirectX Audio には、サウンドの再生以外にもさまざまな機能がある。ハードウェア アクセラレーション、ダウンローダブル サウンド (DLS)、DirectX Media Object (DMO)、および高度な 3D ポジショニング エフェクトを活用するダイナミック サウンドトラックを実装するためのシステムを提供する。

アプリケーションで DirectMusic および DirectSound インターフェイスを使用することによって、次のような処理を行うことができる。

  • MIDI、ウェーブ、または DirectMusic Producer ランタイム形式のファイルまたはリソースからサウンドをロードして再生する。
  • 複数のソースを同時に再生する。
  • 高い精度でミュージック イベントのタイミングをスケジュールする。
  • テンポの変更、パッチの変更、およびその他の MIDI イベントをプログラムによって送信する。
  • ダウンローダブル サウンドを使用する。DLS シンセサイザを使用することによって、アプリケーションは、メッセージベースの曲がどのコンピュータでも同じように再生されることを保証できる。アプリケーションはさまざまな音色を再生でき、個々のノートおよおよびベロシティに応じて独自の音を生成できる。
  • 3D 環境でサウンドを特定する。
  • ピッチの変更、リバーブ、およびその他のエフェクトを簡単にサウンドに適用する。
  • 16 を超える MIDI チャンネルを使用する。DirectX Audio はチャンネル数 16 の制約を打破し、任意の数のボイスをシンセサイザの制限まで、同時に演奏することを可能にした。
  • セグメントを異なるオーディオパスで再生し、エフェクトまたは空間的な広がりを各セグメントに個々に適用する。
  • MIDI データをキャプチャしたり、あるポートから別のポートにストリーミング ("転送") する。
  • マイクまたはその他の入力からウェーブ サウンドをキャプチャする。

DirectMusic Producer または類似するアプリケーションのソース ファイルを使用する場合は、さらに次のような処理が可能である。

  • 別のバリエーションを選択したり、コード進行を変更することによって、実行時に再生のさまざまな面を制御する。
  • 繰り返すたびに若干異なる曲を再生する。
  • ウェーブ サウンドにバリエーションを付けて再生する。
  • パフォーマンス チャンネルをオーディオパスにマップすることによって、同一セグメント内で、部分によって異なるエフェクトを適用する。
  • アルゴリズムによって生成するのではなく、作曲者が指定したコンポーネントに基づいて、実行時にまったく新しい曲を作成する。
  • 既存の曲間のトランジションを動的にアレンジする。
  • トランジション、モチーフ、およびサウンド エフェクトにキューを出して、パフォーマンス内の指定したリズム ポイントで再生する。

DirectX Audio には DirectMusic Producer も含まれている。このアプリケーションによって、作曲者は DirectMusic の機能を最大限に利用するための DLS コレクション、コードマップ、スタイル、およびセグメントを作成できる。また、DirectMusic Producer によって、複数のタイムスタンプを持つウェーブを格納する、再生可能なセグメントを作成できる。これらのウェーブは、圧縮形式でも非圧縮形式でも使用でき、実行時にストリーミングするか、またはメモリ内に全体を格納できる。

アプリケーションを開発する場合、直接 DirectMusic Producer を使用することはないかもしれないが、その機能を広く理解しておくことは、サウンドのデザイン チームとの作業を効率的に進める上で重要である。アプリケーション設計者の観点から見た概要については、「アレンジ用のミュージック要素」を参照すること。詳細については、DirectMusic Producer のマニュアルを参照すること。

DirectX Audio は、Microsoft® Windows® 95、Microsoft Windows 98、Microsoft Windows Me、および Microsoft Windows 2000 において、すべての機能を発揮できる。ただし、ハードウェア シンセサイザを利用できるのは、Windows 2000 および Windows 98 Second Edition 以降のみである。


DirectX Audio 入門

初めて DirectX Audio アプリケーションを作成する場合、複雑な設定は不要である。ただし、現在のバージョンの DirectX がインストールされており、開発環境でヘッダー ファイルへのパスが設定されている必要がある。\lib フォルダ内の DirectX ライブラリ ファイルにリンクできる必要もある。ソフトウェア シンセサイザによって使用される、必要な DLL およびデフォルトの DLS コレクションは、SDK の一部としてシステム ディレクトリにインストールされる。

これ以外に必要なものは、サウンド カード、スピーカまたはヘッドフォン、およびサウンドだけである。以下のいずれかのサウンドを使用できる。

  • MIDI (.mid) ファイル。
  • ウェーブ (.wav) ファイル。
  • DirectMusic Producer のセグメント (.sgt) ファイル。サンプル ファイルは、このアプリケーションと共にインストールされる。その他のファイルは DirectX サンプル アプリケーションに含まれている。

この時点では、DirectMusic Producer によって検索されるその他の種類のファイルは無視できる。コードマップ、スタイル、バンド、および DLS ファイルは再生可能なセグメントのビルディング ブロックであり、それ自体は再生できない。セグメントは、コンテナ ファイルから取得することもできるが、セグメントを抽出するには追加の作業が必要となる。

基本的な作業の詳細については、次のトピックを参照すること。

  • DirectX Audio の基本的な概念
  • サウンド再生の基本的な手順
  • DirectX Audio プロジェクトの作成


DirectX Audio の基本的な概念

ここでは、DirectX Audio の基本的な概念およびそれを実装するオブジェクトを紹介する。

DirectX はコンポーネント オブジェクト モデル (COM) に基づいており、すべての機能はオブジェクトによって実行される。また、ソース データはオブジェクトにカプセル化される。

ここで説明するオブジェクトは、DirectSound だけを使用するアプリケーション以外の、すべての DirectX Audio アプリケーションに公開される。このほかにも多くのオブジェクトが内部で使用されており、高度なアプリケーションによってアクセスすることができるが、ここでは説明しない。

説明するトピックは、次のとおりである。

  • ローダー
  • セグメントとセグメント状態
  • パフォーマンス
  • メッセージ
  • パフォーマンス チャンネル
  • DLS シンセサイザ
  • 音色とダウンロード
  • オーディオパスおよびバッファ


ローダー

ローダー (DirectMusicLoader8) はほかのオブジェクトを取得するオブジェクトである。通常、DirectX Audio アプリケーションで最初に作成されるオブジェクトの 1 つである。

データ オブジェクトはそれ自体を解析し、全体的なロード処理は自動的に実行される。必要な処理は、DirectMusicLoader8 の適切なメソッドを呼び出すことだけである。


セグメントとセグメント状態

セグメントは、シーケンス化されたサウンド データをカプセル化するオブジェクトである。データには、MIDI シーケンス、ウェーブ、DirectMusic Producer のセグメント ファイルの情報のコレクション、または実行時に複数のコンポーネントからアレンジされるミュージックがある。一般的に、セグメントは、1 曲のミュージックまたは 1 つの単位として再生されるその他のサウンドである。

セグメントは、プライマリ セグメントまたはセカンダリ セグメントとして再生できる。プライマリ セグメントは、一度に 1 つだけ演奏できる。セカンダリ セグメントは、一般的に、プライマリ セグメントに重ねて再生される短いモチーフまたはサウンド エフェクトである。

MIDI またはウェーブ ファイルとして生成されたセグメントは、アプリケーションで特殊な処理をしない限り、いつも同じように再生される。一方、DirectMusic Producer でオーサリングされたセグメントには、異なるミュージック パターンや、セグメントを再生するたびにバリエーションを可能にするその他の情報を含めることができる。

セグメントでは、ウェーブ、パターン、コード変更、バンド変更、テンポ変更など、異なる種類のデータを組み合わせることができる。各種のデータはトラック オブジェクトにカプセル化される。Visual Basic で作成されたアプリケーションでは、トラック オブジェクトにアクセスできない。またセグメントは、特殊効果など、そのセグメントを再生するオーディオパスに関する情報も格納できる。

DirectMusic Producer のセグメントには、ほかのロード可能なミュージック コンポーネントへの参照を含めることもできる。たとえば、あるバンドを使って作成されたセグメントからそのバンド オブジェクトを取得できる。

セグメントを再生するたびに、セグメント状態オブジェクトが作成される。アプリケーションでは、このオブジェクトを使用して、再生の状態および再生中のセグメントのインスタンスのオーディオパスに関する情報を取得できる。


パフォーマンス

パフォーマンス オブジェクトは、ソースからシンセサイザまでのデータ フローを管理する。通常、アプリケーションはパフォーマンスを 1 つだけ持つ。

パフォーマンスは、タイミング、データ チャンネルとオーディオパスへのマッピング、メッセージのルーティング、ツール管理、通知、およびその他の重要なタスクを処理する。


メッセージ

オーディオ データは、メッセージの形でパフォーマンスに渡される。パフォーマンス メッセージは MIDI メッセージに似ているが、より多くの、より多様な情報を含んでいる。メッセージには、ノート、ウェーブ、またはコントローラの変更に関する情報を含めることができる。また、歌詞を表示するためのテキストを含めることもできる。

多くのアプリケーションでは、セグメントの再生中にトラックによって生成されるメッセージを直接処理しない。ただし、アプリケーションでパフォーマンスにメッセージを挿入することは可能である。

また、通知にはメッセージも使用される。アプリケーションは、パフォーマンスが特定のポイントに達するたびにイベントが通知されるように要求できる。たとえば、音楽の拍子ごとにイベントを通知できる。パフォーマンス メッセージにはそのイベントに関する情報が含まれている。


パフォーマンス チャンネル

再生中のサウンドは 1 つまたは複数のパートで構成される。パートには MIDI チャンネル、DirectMusic Producer セグメントのパート、またはウェーブがある。通常、パートは 1 つの楽器に対応する。

パフォーマンス チャンネルは、パートとオーディオパスとの間のルートである。パートに関する情報を含む各メッセージは、メッセージが正しくルーティングされるようにパートのパフォーマンス チャンネルも指定する。

パフォーマンス チャンネルは MIDI チャンネルによく似ているが、従来の MIDI 再生は 16 チャンネルに制限されていたのに対し、パフォーマンス チャンネルでは実質上無制限である。


DLS シンセサイザ

MIDI ノートなど、ウェーブ形式になっていないデータをサウンド カードで再生するには、ウェーブ形式に変換する必要がある。この変換は、シンセサイザによって行われる。

DirectX Audio は一部のオペレーティング システムで基本的な MIDI 合成をサポートしているが、多くのアプリケーションは Downloadable Sounds (DLS) Level 2 規格を実装するシンセサイザを使用する。適切なハードウェア シンセサイザがない場合は、Microsoft のソフトウェア シンセサイザが使用される。

シンセサイザは、ウェーブ サンプルに基づいてサウンドを生成する。これによって、あらゆる種類のサウンドに加え、高度なティンバーも生成できる。

注 DirectX 7 インターフェイスと共に使用される DLS Level 1 シンセサイザには、リバーブ機能が含まれており、デフォルトで有効になっている。Waves TrueVerb リバーブ テクノロジが Microsoft にライセンスされており、SimpleVerb として実装されている。

DirectX 8.0 と共に使用される DLS Level 2 シンセサイザには、組み込みのリバーブ機能は含まれていない。その代わり、リバーブは DMO として実装されている。このために Waves MaxxVerb が Microsoft にライセンスされている。


音色とダウンロード

音色を再生するために、シンセサイザはその音色がどのように聞こえるかについての情報を持っている必要がある。この情報は、ウェーブ サンプルおよびアーティキュレーション データで構成され、DLS コレクションに格納される。音色のデータは、ダウンロードすることによってシンセサイザで使用できるようになる。

通常、1 つの音色のさまざまなノートは、同じ 1 つのサンプルに各ノートのピッチを割り当てることによって生成される。ただし、DLS Level 2 を使用すると、異なるサンプルまたはサンプルの組み合せに基づいて各ノートを生成できる。ノートのベロシティをトリガとして、基本の音色の異なるサンプルを使用することもできる。

デフォルトでは、Microsoft のソフトウェア シンセサイザは Roland GM/GS コレクションの DLS データを利用する。デフォルトのコレクションには、General MIDI 規格で定義されている 128 の音色の DLS データが含まれている。カスタム コレクションには、任意の種類の音色を含めることができる。音色のウェーブ サンプルは楽器の音色に基づいている必要はない。サウンド エフェクト、演説の一部、作成済みの完全な小節など、録音された任意のサウンドを使用できる。

必要なデータはデフォルトのコレクションに含まれているか、セグメントに関連付けられたバンド オブジェクトによって参照されるので、ほとんどのアプリケーションでは直接コレクションにアクセスする必要がない。バンドは、音色とパフォーマンス チャンネルにマップされた設定とのセットである。バンドの音色を使用する前にダウンロードされるようにするには、いくつかの手法がある。

注 Roland GM/GS Sound Set を修正することはできない。「法的情報」の「著作権に関する注意」を参照すること。

ウェーブ ファイルおよびリソースも、再生するにはシンセサイザにダウンロードする必要がある。


オーディオパスおよびバッファ

各 DirectMusic セグメントは、パフォーマンスからシンセサイザへのサウンドのフローを制御するオーディオパス上で再生され、次に DirectSound バッファでエフェクトが適用され、最後にプライマリ バッファで最終的な出力がミキシングされる。

アプリケーションは標準オーディオパスを作成し、そのオーディオパスでセグメントを再生できる。たとえば、ミュージック リバーブが設定されたバッファで MIDI ファイルを再生するオーディオパスと、3D コントロールが設定されたバッファでウェーブ ファイルを再生するオーディオパスをアプリケーションで作成できる。

DirectMusic Producer では、さらに高度なオーディオパスの構成からセグメントを作成できる。たとえば、標準以外の構成で、セグメント内のパートを異なる DirectSound バッファに送信し、異なるエフェクトを適用することができる。

オーディオパスは、データがストリーミングされる一連のオブジェクトと見なすことができる。アプリケーションはこれらのオブジェクトのすべてにアクセスできる。たとえば、バッファ オブジェクトを取得して音源の 3D プロパティを設定したり、エフェクト DMO を取得してエフェクトのパラメータを変更できる。


サウンド再生の基本的な手順

「DirectX Audio の基本的な概念」で説明されている基本的な項目を理解したら、次にアプリケーションで基本的なサウンドトラックを実装する。簡単な手順を学習した後、必要に応じてサウンドトラックを細かく制御するための API について学習することができる。

ここでは、コーディングの詳細には触れずに、必要な手順の概要について説明する。サンプル コードについては、「チュートリアル 1 : オーディオ ファイルの再生」を参照すること。

サウンドを生成するには、アプリケーションで次の処理を行う必要がある。

1. パフォーマンスの作成と初期化

ほとんどのアプリケーションはパフォーマンス オブジェクトを 1 つだけ使用する。パフォーマンス オブジェクトは、DirectX8.DirectMusicPerformanceCreate を呼び出すことによって作成できる。次に、DirectMusicPerformance8.InitAudio を呼び出す。このメソッドによって、デフォルトのオーディオパスを設定できる。

2. ローダーの作成

DirectX8.DirectMusicLoaderCreate を呼び出して、DirectMusicLoader8 オブジェクトを取得する。この処理は一度だけ行う必要があり、アプリケーションを終了するまで同じローダー オブジェクトを使用する必要がある。

3. セグメントのロード

ローダーがデータ ファイルを見つけることができるように、DirectMusicLoader8.SetSearchDirectory を呼び出す。次に、DirectMusicLoader8.LoadSegment または DirectMusicLoader8.LoadSegmentFromResource を呼び出して、ファイルまたはリソースから DirectMusicSegment8 オブジェクトを取得する。

4. バンドのダウンロード

DLS データをシンセサイザにダウンロードすると、音色を再生できる。ウェーブ ファイルもダウンロードする必要がある。最も簡単な方法は、DirectMusicSegment8.Download を呼び出す方法である。

5. セグメントの再生

セグメント ポインタを DirectMusicPerformance8.PlaySegmentEx に渡す。

この処理の詳細については、次のトピックを参照すること。

  • オーディオ データのロード
  • サウンドの再生

注 DirectSound インターフェイスだけを使用してウェーブ サウンドを再生することもできる。ただし、このような処理を行うには、自分でデータ ソースを解析し、バッファへのデータのストリーミングを処理する必要がある。詳細については、「DirectSound でのウェーブの再生」を参照すること。


DirectX Audio プロジェクトの作成

プロジェクトで DirectX for Visual Basic を使用するには、まずプロジェクトからタイプ ライブラリにアクセスできるようにする必要がある。

  1. Visual Studio で、[プロジェクト] メニューの [設定] をクリックする。[設定] ダイアログ ボックスが表示される。
  2. [DirectX 8 for Visual Basic Type Library] の横にあるチェック ボックスをオンにして、[OK] をクリックする。


DirectX Audio について

ここでは、DirectMusic および DirectSound API の詳細には触れず、DirectX Audio の基本的な処理について説明する。「DirectX Audio の基本的な概念」で示されている概念の理解を深めることを目的としている。API の使い方については、「DirectX Audio の使い方」を参照すること。

説明するトピックは、次のとおりである。

  • DirectSound と DirectMusic
  • オーディオ データの流れの概要
  • アレンジ用のミュージック要素
  • 再生中の音楽の変化
  • ミュージック値と MIDI ノート
  • ダウンローダブル サウンド
  • オーディオ スクリプト


DirectSound と DirectMusic

以前のバージョンの DirectX では、2 つの独立したコンポーネントでオーディオ機能を提供していた。DirectSound と DirectMusic である。DirectSound はデジタル サンプル (ウェーブ) を再生およびキャプチャするためのもので、DirectMusic は単純な MIDI ファイルから、DirectMusic Producer で作成されるミュージック セグメントまで、さまざまなメッセージベースのデータを再生するためのものである。DirectMusic は、DLS を使用することによって音楽以外のサウンド エフェクトを再生できたが、以前はその重点は音楽の再生機能に置かれていた。

DirectX 8 では、DirectMusic インターフェイスがすべてのサウンドのロードおよび再生の主要なメカニズムである。サウンドがウェーブ フォーマット、MIDI フォーマット、DirectMusic Producer フォーマット、またはアドオン ローダーやツールで使用可能な任意の形式のどのファイルまたはリソースとして作成されているかは関係ない。

アプリケーションではウェーブの再生に DirectSound インターフェイスを使用することができ、ウェーブ キャプチャのための API として DirectSoundCapture が残されている。ただし、ほとんどのアプリケーションでは、DirectSound は DirectMusic シンセサイザからダウンストリームの処理を行う。シンセサイザからの出力をエフェクト フィルタにルーティングし、3D エフェクトを適用し、データを出力デバイスにストリーミングする前の最終的なミキシングを行う。

以前に DirectSound を使用していた場合は、ウェーブのロードおよび再生を DirectMusic インターフェイスに切り替えることによって、次のような利点がある。

  • ファイルやリソースを解析する必要がない。この処理は DirectMusic ローダーによって行われる。
  • DirectSound でサポートされていないウェーブ フォーマットについては、自動的に Windows オーディオ圧縮マネージャ (ACM) が使用される。
  • データの自動的なストリーミング。手動でバッファを作成したり、読み書きポインタを記録する必要がない。
  • タイミング制御の向上。DirectMusic マスタ クロックを使用して正確にサウンドをスケジュールできるだけでなく、サウンド エフェクトと音楽を容易に同期化できる。
  • サウンドの複数のインスタンスを容易に管理できる。

DirectMusic Producer ファイルに組み込まれるウェーブには、さらにいくつかの利点がある。エンベロープなどの DLS アーテイキュレーション エフェクトをウェーブに追加できる。セグメントに複数のバリエーションのウェーブを含めて、再生にランダムな要素を加えることができる。

これらの利点は、DirectSound によって提供される下位レベルの制御が失われることを意味しない。DirectMusic API によって、オーディオパスの任意のオブジェクトにアクセスできる。既存のバッファのインターフェイスを取得したい場合は、容易に取得できる。フィルタやエフェクトを追加するために、DirectSound API のすべての新機能を利用することもできる。


オーディオ データの流れの概要

一般的に、DirectX Audio アプリケーションは、次に示すような 1 つまたは複数のソースからミュージック データを取得する。

  • MIDI ファイル
  • ウェーブ ファイル
  • DirectMusic Producer または類似のアプリケーションで作成されたセグメント ファイル
  • DirectMusic Producer などのアプリケーションでオーサリングされ、コンポーザ オブジェクトによって完全にアレンジされたコンポーネント ファイル

注 これらのデータ ソースは、個別のファイルではなく、リソースとしてアプリケーションに格納することができる。

これらのソースからのデータは、セグメント オブジェクトにカプセル化される。各セグメント オブジェクトは、1 つのソースからのデータを表す。パフォーマンスのある時点では、1 つのプライマリ セグメントと任意の数のセカンダリ セグメントを再生できる。ソース ファイルは混在させることができる。たとえば、ウェーブ ファイルに基づくセカンダリ セグメントを、オーサリングされたセグメント ファイルと共に演奏することができる。

1 つのセグメントには 1 つ以上のトラックが含まれ、それぞれがノートやテンポの変更など、特定の種類のタイム データを含んでいる。ほとんどのトラックは、セグメントがパフォーマンスによって再生されるときに、タイムスタンプ メッセージを生成する。一部のトラックは、パフォーマンスから問い合わせがあったときに、データだけを提供する。

まず、パフォーマンスは、アプリケーションが定義したツールにメッセージをディスパッチする。それらのツールはセグメント ツールグラフにグループ化される。セグメント ツールグラフは、特定のセグメントからのメッセージ、そのオーディオパスで再生されるすべてのセグメントからのメッセージのオーディオパス ツールグラフ、すべてのセグメントからのメッセージを受信するパフォーマンス ツールグラフのみを処理する。ツールでメッセージを変更して渡したり、削除したり、新しいメッセージを送信することができる。

注 アドオン ツールは、DirectX for Visual Basic ではサポートされていない。

最終的に、メッセージは出力ツールに到達する。出力ツールで、データは MIDI フォーマットに変換されてからシンセサイザに渡される。チャンネル固有の MIDI メッセージは、シンセサイザの適切なチャンネル グループに転送される。シンセサイザはサウンド ウェーブを作成し、シンクと呼ばれるデバイスにストリーミングする。シンクは、バスを介した DirectSound バッファへのデータの配信を管理する。

バッファには、以下の 3 つの種類がある。

  • シンクイン バッファは、シンクがデータをストリーミングする DirectSound のセカンダリ バッファである。このバッファは、必要に応じて、データ形式をプライマリ バッファのデータ形式に変換し、アプリケーションがパン、ボリューム、3D 空間の広がり、およびその他のプロパティを制御できるようにする。また、エフェクト モジュールを介してデータを渡し、リバーブやエコーなどのエフェクトを追加することもできる。生成されたウェーブフォームは、プライマリ バッファに直接渡されるか、1 つ以上のミックスイン バッファに渡される。
  • ミックスイン バッファは、ほかのバッファからデータを受け取り、エフェクトを適用し、ウェーブフォームをミキシングする。このバッファを使用して、グローバル エフェクトを適用できる。データをミックスイン バッファに送信することによって得られるエフェクトをセンドと呼ぶ。
  • プライマリ バッファは、すべてのデータの最終的なミキシングを行い、レンダリング デバイスに渡す。

注 アプリケーションでは、DirectMusic のパフォーマンスの一部であるセカンダリ バッファを介してデータをストリーミングする必要はない。アプリケーションでは、エフェクトを追加したり、プロパティを変更するために、バッファ オブジェクトを取得できるが、DirectSound API を使用してウェーブ サウンドを再生する場合のように、バッファをロックして書き込むことはできない。

次の図は、ファイルからスピーカへのデータ フローの概略図である。複数のセグメントを同時に再生できるが、ここでは 1 つのセグメントだけが示されている。セグメントは、4 つのソースのいずれかのみからデータを取り出す。使用できるソースは、ウェーブ ファイル、MIDI ファイル、DirectMusic Producer で作成したセグメント ファイル、およびコンポーザ オブジェクトによって結合されたコンポーネント ファイルのいずれかである。

注 いずれの場合も、ファイルではなく、リソースのデータを使用できる。

パフォーマンスにおけるメッセージの流れを詳細に確認するには、「DirectMusic メッセージの使い方」を参照すること。

この図に示されているプロセスの実装方法については、「オーディオ データのロード」および「サウンドの再生」を参照すること。


アレンジ用のミュージック要素

DirectX Audio を最大限に活用すると、MIDI ファイルやウェーブ ファイルの再生以外の処理も行うことができる。DirectMusic Producer などのアプリケーションでオーサリングされたミュージック要素を利用して、さまざまな方法で変更または操作できるパフォーマンスを作成できる。

注 このマニュアルでは、DirectMusic のコンポーザ オブジェクトとの混同を避けるために、ミュージック要素を作成する人間のコンポーザ (作曲者) をオーサーと表現する。同様に、ミュージック要素は、作曲ではなく、オーサリングするという。

以下に示すこれらの要素の簡単な説明とそのオーサリング方法は、アプリケーション開発者がパフォーマンスで使用されるマテリアルを理解できるようにするためのものである。詳細については、DirectMusic Producer のマニュアルを参照すること。これらの要素をアプリケーションに組み込む方法については、「アレンジ要素の使い方」を参照すること。

次のアレンジ要素について説明する。

  • スタイル
  • コードマップ
  • スタイル ベースのセグメント
  • MIDI ベースのセグメント
  • テンプレート
  • バンド


スタイル

スタイルは、ダイナミック スコアの作成に使用される音楽パターンのコレクションである。また、拍子記号やテンポを含み、1 つまたは複数のバンドを含むこともできる。

パターンは、1 小節以上の長さの音型で、各音色の基本的な一連のノート、つまりパートで構成される。これらのノートは固定されていないが、最終的には、現在のキー、コード、および演奏モードに応じて、特定のピッチに割り当てられる。パターンには、バリエーションも含まれる。

モチーフは、基本スコア上でダイナミックに演奏されるようにデザインされた、特殊なパターンである。通常、モチーフはインタラクティブ アプリケーションでイベントをマークするために使われる。

DirectMusic Producer では、オーサーはピアノ ロールに似たグリッドを使ってパターンを作成する。各パートは (パフォーマンス チャンネルに対応する) 独自の行を持ち、ノートはバーの長さ (持続時間)、太さ (ベロシティ)、縦軸方向の位置 (ピッチ)、および横軸方向の位置 (時間) で表される。

オーサーは、各パターンに対して多くのバリエーションを作成することができる。通常は、パターンをコピーして一部をわずかに変更することにより、バリエーションを作成できる。スタイルの再生メカニズムによって、実行時にバリエーションが選択される。ただし、オーサーは任意のコードに対してバリエーションを無効にすることもできる。つまり、特定のコードが演奏されているときは、あるバリエーションを決して選択しないよう指定できる。

オーサーは、パターンにグルーブ範囲を割り当てて、パターンを演奏できるグルーブ レベルを指定することもできる。

パターンは、装飾として指定することもできる。装飾には、イントロ、フィル、ブレーク、エンド、およびカスタムの 5 種類があり、これらの 1 つまたは複数のカテゴリに、パターンを割り当てることができる。音楽の演奏中に特定の装飾が呼び出されると、その種類のパターンのみが再生の候補となる。


コードマップ

現代の音楽の多く、特にポピュラー、ロック、フォーク、ジャズの特色はコード進行の概念に基づいており、特定の時間枠に演奏されるすべてのノートが特定のコードに関連付けられていること、および音楽はあるコードから別のコードへと調和的に移行することを意味する。

DirectMusic 用にオーサリングされたパターンにあるノートは、1 つのコードから派生しているか、コードと調和するよう意図されたものである。しかし実行時に、パターンはコード進行に合わせて転置する。つまりベース コードの変化に応じて、DirectMusic はノートのピッチを変更する。

コードマップは、コード進行のロード マップである。コードマップ デザイナを使って、オーサーは希望の音楽感やパーソナリティを表現できるコードを選択する。これらのコードは、タイム ラインに沿ったフローチャートに従ってアレンジされる。タイム ラインには循環という概念があるので、ミュージック セクションの演奏が続く間、最初に戻ってループを形成する。

特定の重要なコードをサインポストとして指定する。これらは、特定のポイントで演奏されなければならないコードである。音楽は、常にサインポストからサインポストへと移行する。しかし、サインポスト間のコード進行は、オーサーの指定したマップに従ってさまざまなルートをたどることもできる。

コード チャート内のルートは、コンポーザ エンジンによって実行時に選択することができる。この場合、パターン自体のバリエーションに追加してバリエーションが提供される。オーサーがセグメントを作成する際に、オーサリング ツールを使ってルートを選択することもできる。

コードマップのコードは、サブコードと呼ばれる、複数の異なるコードで構成することができる。同じコードを異なる転回で演奏して多調性を得るために、オーサーは異なるサブコードに別のパートを割り当てることができる。各サブコードは、1 つまたは複数のレベルで有効であり、スタイルのポートに割り当てられたレベルで調和する。


スタイル ベースのセグメント

スタイル ベースのセグメントは、あらかじめ作成された、音楽の大きなピースであり、オーサーは次の要素を使ってセクションを構築する。

  • スタイル。スタイルは、パターンと同様、音楽に関する一般的な情報 (拍子記号やテンポなど) で構成される。「スタイル」を参照すること。
  • コード進行。オーサリング ツールがコードマップから自動的に派生したもの (コード チャートからパスを選択する)、またはオーサーが手作業で入力したもの。
  • コマンド トラック。DirectMusic Producer のグルーブ トラックとして知られているこのトラックは、設定時の適切なパターンを選択するための一連のコマンドである。スタイル中のパターンの特徴は、装飾 (イントロ、フィル、ブレーク、およびエンド) として指定できること、およびオーサーが特定のグルーブ範囲を割り当てることができることである。セグメントのコマンド トラックは、スタイル再生エンジンに対して、イントロ パターンを選択して最初の小節で演奏し、次の 4 小節でグルーブ レベルが 25 のパターンのみを再生した後、ブレークを演奏する、などの動作を指示することができる。
  • バンド。オーサーは、音色とパフォーマンス チャンネルを、さまざまなパターンのすべてのパートに割り当てることができる。


MIDI ベースのセグメント

MIDI ベースのセグメントは、普通は MIDI ファイルをインポートして DirectMusic Producer で作成し、ここでオーサーは、ループ ポイントだけでなく、テンポ、キー、バンドの変更を追加できる。スタイル ベースのセグメントと異なり、MIDI セグメントにはパターンおよびコマンド トラックがない。これらの代わりにシーケンス トラックがあり、MIDI ノートとその他のコマンドはここに含まれる。


テンプレート

テンプレートは、サインポスト トラックとコマンド トラック (オプション) を格納できる。サインポスト トラックを使用して、そのセグメント自体またはサインポスト トラックを持たない別のセグメントの新しいコード進行を作成できる。コマンド ドラックは、グルーブ レベルおよび装飾を提供する。実行時にテンプレートを使用して、新しいマテリアルを作成することもできる。

注 DirectX 8.0 以前のバージョンの DirectMusic Producer で作成したテンプレートは、再生可能な独立したセグメントではない。これらは、ほかのセグメントをアレンジするためにだけ使用できる。

サインポスト トラックには、コード進行のバリエーションが認められるリージョンの先頭と最後をマークする一連のサインポスト マーカーが含まれる。各サインポスト マーカーは、コードマップ内の特定のグループのサインポスト コードについてのみ有効である。コンテンツのオーサーは、サインポスト マーカーおよびサインポスト コードを適切なグループに割り当てる必要がある。

DirectMusic では、サインポスト トラックを特定のスタイルおよびコードマップに適用することによってセグメントをアレンジする。テンプレート内のタイム ラインに沿ってコンポーザがサインポスト マーカー ペアを見つけるたびに、コンポーザはそのグループに所属するサインポスト コードのペアに対応するコードマップを検索する。ペアが見つかり、そのペア間の間隔が利用可能な時間に適合する場合は、エンジンはコードマップで定義されている 2 つのサインポスト コード間の固定コード進行に従う。ペア間の適切なパスが見つからない場合や、エンド サインポスト マーカーが存在しない場合は、エンジンは開始サインポスト マーカーから派生した任意のコードを演奏する。

アプリケーションでテンプレートからセグメントをアレンジする方法については、「テンプレートの使い方」を参照すること。


バンド

バンドとは一連の音色にそれぞれのパフォーマンス パラメータを組み合わせ、音楽のピース内の特定のパートを組み合わせたものである。バンドは DLS コレクションと同じではない。DLS コレクションはシンセサイザにダウンロードできる音色のセットを表し、任意のアプリケーションから利用することができる。

オーサーは DirectMusic Producerのようなツールを使って、音色をパフォーマンス チャンネルに割り当てることによりバンドを作成する。これらの音色は任意の DLS コレクションから取得することができ、別のソースの音色を 1 つのバンドに混在させることもできる。それぞれの音色には、ボリューム、パン、転調が設定される。

パフォーマンス チャンネルは、音色をパートに割り当てる。パターンがチャンネル 1 の特定のノートを呼び出す場合、このノートはチャンネル 1 に割り当てられている現在のバンドの音色で演奏される。サウンドは、バンドで設定されている音色のボリューム、パン、および転調の値で修正される。

バンドは個別のファイルに保存するか、スタイルやセグメントに含められる。


再生中の音楽の変化

DirectMusic がスタイルベースのセグメントを演奏するとき、基本的な和音とリズムに変更が加えられるので、演奏に変化が表われる。変更の一部はスクリプト化され、一部はランダムに行われる。

  • パターンの選択。一般的なスタイルには複数のパターンが含まれる。これらのパターンは、コマンド トラックからのコマンドに応じて選択される。たとえば、コマンド トラックがブレーク装飾の演奏を要求すると、スタイル再生エンジンは現在のグルーブ レベルに矛盾しないブレーク パターンを選択する (オーサーは、各パターンにふさわしいグルーブ レベルを指定する)。適切なパターンがいくつかある場合は、オーサーによってセグメントに埋め込まれたルールに従ってパターンが選択される。パターンは完全または部分的にランダムに選択されることもあれば、特定のシーケンスで選択されることもある。
  • パターン内のバリエーション。パターン内のパートには、複数のバリエーションを設定することができる。バリエーションは、オーサーが指定した順序で演奏することができる。それ以外の場合は、パターンの各繰り返しにおいて、スタイル再生エンジンがバリエーションをランダムに選択する。
  • グルーブ レベル。セグメントの現在のグルーブ レベルにより、スタイル内のどのパターンを再生用に選択できるかが決まる。現在のレベルを設定するのはコマンド トラックであるが、コマンド トラックは通常、セグメントかテンプレートの一部としてオーサリングされる。セグメントの現在のグルーブ レベルは、プログラム的に変更することができる。パフォーマンスのマスタ グルーブ レベルを設定することで、変更をすべてのセグメントに適用することができる。
  • 転調。セグメントを演奏するときに、ベース コードはコード トラックの進行に従って変化する。現在のパターンのノートは、新しいコードと調和するよう、自動的に転置される。
  • タイミングのバリエーション。再生エンジンは、個々のノートのパラメータ、つまりノートの開始時期と終了時期に、ランダムな変更を加えることができる。
  • バンド。セグメントの演奏中に、音色と音色の設定 (ボリューム、パン、および転調) の選択を、オーサリングされたセグメント内のバンド トラックで変更したり、アプリケーションで動的に変更することができる。アプリケーションでバンドを変更するには、バンド オブジェクトに基づくセカンダリ セグメントを作成してそのセグメントを演奏するか、演奏中のセグメントのバンド トラック上にパラメータを設定する。

アプリケーションはほとんどの場合、既存のセグメントを操作するのではなく、別のセグメントを演奏して音楽全体を制御する。たとえば、ゲームのインテンシティの変化を音楽に反映させるには、インテンシティ レベルに応じてオーサリングされた新しいセグメントにトランジションするだけでよい。オーサーにグルーブ範囲の異なるパターンを作成させ、ゲーム イベントに応じてグルーブ レベルを変更すると、1 つのスタイル ベースのセグメントでも同様のエフェクトを得ることができる。


ミュージック値と MIDI ノート

DirectMusic スタイル内のパターンのノートは、固定されたノートではない。これらのノートは、現在の演奏モードとサブコード レベルに応じて現在のコードに転置されたときにだけ実際のノートとなる、ミュージック値である。

ミュージック値は、ノートの意図的な役割を表すものである。たとえば、ミュージック値で、ノートをコードの 2 番目の位置、1 つ上のスケールで演奏するように指定することができる。このミュージック値が特定のコードに適用されると、そのコードの 2 番目で、1 つ上のスケールの適切な MIDI ノートに変換される。

コードに対してノートがどのように解釈されるかは、演奏モードによって異なる。たとえば、モードが DMUS_PLAYMODE_NORMALCHORD の場合、ノートはコードのルート音に基づいて、コードとスケールの音程として解釈される。モードが DMUS_PLAYMODE_FIXEDTOKEY の場合、ノートは線形な値として解釈される。

複数の並行するコード進行を使って複雑な和音を可能にするために、DirectMusic コードは複数のサブコードで構成できる。サブコード レベルは 0 ～ 31 の値で、ミュージック値の確立に使用できるコードのサブコードを決定する。各サブコードは、オーサーの定義に従って、1 つまたは複数のレベルで有効である。DirectMusic Producer は、1 つのコードに対して最高 4 つのサブコードをサポートする。

ミュージック値のデータ形式の説明については、「DMUS_NOTE_PMSG」を参照すること。各演奏モードの詳細については、「CONST_DMUS_PLAYMODE_FLAGS」を参照すること。


ダウンローダブル サウンド

これまで、ほとんどのコンピュータ音楽は、次の 2 つの方法のいずれかで生成されていた。それぞれに利点はあるが、欠点もある。

  • 通常は .WAV ファイル、またはレッドブック オーディオ規格に従った標準的な CD トラックに記録されているデジタル サンプルからウェーブフォーム (波形) を再現する方法。デジタル サンプルではどのようなサウンドも再現可能で、どのサウンド カードを使った場合でも得られる出力は非常によく似ている。ただし、ストリーミング用に多くの記憶領域とリソースが必要となる。
  • 一般的には MIDI ファイルからのメッセージに応答して、音色のサウンドを通常はハードウェアで合成する方法。MIDI ファイルはコンパクトで、ストリーミング リソースもわずかしか必要としないが、出力は General MIDI セットのシンセサイザで利用できる音色の数に限定され、システムによっては非常に異なった音になる場合がある。

デジタル サンプリングの利点と、MIDI のコンパクトさ、および柔軟性を組み合わせる 1 つの方法が、ウェーブテーブル合成である。これは、デジタル サンプルから音色のサウンドを合成する方法である。実際の音色をレコーディングすることによってサンプルを取得し、ハードウェアに保存する。さまざまなピッチとボリュームで任意の長さのサウンドを作成するために、サンプルのループと調整が行われる。

ウェーブテーブル合成はアルゴリズムに基づく FM 合成より現実的なティンバーを作成するが、依然として固定セットの音色に限定される。さらに特定の音色のサウンドはメーカーの実装によって異なり、ハードウェアの組み合わせが異なると非常に異なったサウンドになる場合がある。

次に、MIDI Manufactures Association によって発表された、ダウンローダブル サウンド (DLS) 規格がある。DLS は、システムにハードワイアードで実装されたサンプルの代わりに、実行時に提供されるサンプルに基づいてウェーブテーブル合成を行うことができる方法である。音色を記述するデータはシンセサイザにダウンロードされ、その後はほかの MIDI 音色と同様にその音色を演奏できる。DLS はアプリケーションの一部として配信できるため、開発者はサウンドトラックをすべてのシステムで同じように演奏させることができる。また、音色の選択が制限されることもない。

DLS 音色は 1 つまたは複数のサンプルから作成され、通常はシングル ピッチを表すが、シンセサイザで変更を加えることによりその他のピッチを作成できる。広範囲のピッチで音色のサウンドを現実的にするには、複数のサンプルを使う。DLS 音色をダウンロードする際に、リージョンと呼ばれる特定のピッチ範囲が各サンプルに割り当てられる。

DLS Level 2 では、すべてのノートにそれぞれのリージョンを割り当てることができる。また、各リージョンのティンバーをレイヤと呼ばれる複数のサンプルから作成したり、ノートのベロシティに応じて異なるレイヤをトリガすることができる。これによって、1 つの音色から無数のサウンドを作成できる。

加えて、サンプルにアーティキュレーションを与えることもできる。これはサウンドを実際の音色により近づけるための特徴を定義する。アーティキュレーションには、サウンドのボリュームやピッチのエンベロープおよびビブラートやトレモロを提供する低周波数発振器 (LFO) が含まれる。

サンプルは、ループ可能にすることも、単発にすることもできる。ループ可能なサンプルは、ノートの継続時間の間、繰り返し演奏される。単発のサンプルは一度だけ演奏される。

DLS データは音色コレクションに格納され、ここからシンセサイザにダウンロードされる。

ほかの MIDI 音色の場合と同様に、DLS 音色にはパッチ番号が割り当てられ、MIDI メッセージに応答する。ただし、DLS 音色 (機器) は General MIDI セットに従う必要はない。実際、ミュージックの音色である必要はまったくない。演説の一部や作成済みの完全な小節など、どんなサウンドでも DLS 音色に関連付けることができる。

DLS コレクションと DLS 音色の作成方法の詳細については、DirectMusic Producer のドキュメントを参照すること。DLS 規格の詳細については、MIDI Manufacturers Association から入手可能な『Downloadable Sounds Level 2』を参照すること。

ほとんどのアプリケーションは音色や DLS データを直接扱う必要がない。コレクションを開いたり、音色データをダウンロードする処理は、バンド オブジェクトによって実行される。バンドをダウンロードすると、そのバンドに関連付けられているすべての音色データもダウンロードされる。詳細については、「バンドの使い方」を参照すること。


オーディオ スクリプト

オーディオ スクリプトは、アプリケーション内からアクセスできる変数とルーチンを含むファイルである。Microsoft® Visual Basic® Scripting Edition の AudioVBScript と呼ばれるサブセットで記述される。DirectMusic Producer にはスクリプトのオーサリング環境が含まれており、スクリプトはバイナリ パラメータとスクリプトのテキストを含む特殊な形式で保存される。

スクリプトは主な DirectX Audio オブジェクトのいくつかを実装し、次のような基本的な機能を実行できる。

  • オーディオパスの作成
  • オーディオパスのボリュームの設定
  • パフォーマンスのグローバル パラメータの設定
  • セグメントのロード、演奏、および停止
  • バンドのダウンロード

DirectX® for Visual Basic では、アプリケーションが API を使ってオーディオ スクリプトのロードおよび呼び出しを行うことはできない。ただし、DirectMusic Producer で作成するセグメントにスクリプト トラックを含めて、スクリプト内のルーチンの呼び出しをトリガすることができる。


DirectX Audio の使い方

ここでは、アプリケーション開発における Microsoft® DirectMusic® および Microsoft® DirectSound® API の使用方法を説明する。

説明するトピックは、次のとおりである。

  • オーディオ データのロード
  • サウンドの再生
  • パフォーマンス パラメータ
  • オーディオパスの使い方
  • 3D サウンド
  • エフェクトの使い方
  • バッファ チェーン
  • アレンジ要素の使い方
  • オーディオ スクリプトの使い方
  • DirectSound でのウェーブの再生
  • サウンド キャプチャ

一般的な概要については、「DirectX Audio 入門」を参照すること。

基本的なデータ フローのメカニズムについては、「DirectX Audio について」を参照すること。

特殊なアプリケーションで使用される高度な機能については、「DirectX Audio の高度なトピック」を参照すること。


オーディオ データのロード

DirectMusic オブジェクトをパフォーマンスに組み込む前に、それらをファイルまたはリソースからロードしなければならない。DirectMusicLoader8 クラスは、これらのオブジェクトのロードを管理するために使用される。

ほとんどの場合、アプリケーションでは、既存の DirectMusicLoader8 オブジェクトを、一度に 1 つだけ使用するべきである。1 つのグローバル ローダー オブジェクトを作成し、ロードがすべて終了するまでオブジェクトを解放しないようにする。この方法により、オブジェクトが効果的に検索およびロードされる。

ただし、アプリケーションがセグメントを何度もロードすることがある場合は、DirectMusic が内部で使用しているキャッシュ システムのために、以前に使用していたものと同じセグメント オブジェクトが取得され、開始およびループ ポイントや DLS コレクションへの接続などの設定が、以前の設定と同じであることに注意する。これを避けるには、セグメントを再ロードする前に、DirectMusicLoader8 オブジェクトを Nothing に設定して解放し、新しいオブジェクトを作成する。

ほかのオブジェクトによって参照されるオブジェクトのロードは、透過的に処理される。たとえば、DirectMusic Producer からロードされるスタイルに、ほかのファイルにデータがあるバンドへの参照が含まれているとする。DirectMusic は自動的にバンドをロードし、アプリケーションは DirectMusicStyle8.GetBand メソッドを使ってこれを取得する。

ローダーの使用方法の詳細については、次のトピックを参照すること。

  • ローダーの検索ディレクトリの設定
  • ファイルからのオブジェクトのロード
  • リソースからのオブジェクトのロード
  • コンテナ


ローダーの検索ディレクトリの設定

デフォルトでは、ロード メソッドにフル パスを渡さない限り、ローダーはカレント ディレクトリのファイル オブジェクトを検索する。DirectMusicLoader8.SetSearchDirectory メソッドを使うと、DirectMusicLoader8.LoadBand、DirectMusicLoader8.LoadCollection、DirectMusicLoader8.LoadSegment、および DirectMusicLoader8.LoadStyle の各メソッドに異なるデフォルト パスを設定できる。


ディレクトリでのオブジェクト検索

ここでは、C++ でのアプリケーション開発について説明する。


オブジェクトの列挙

ここでは、C++ でのアプリケーション開発について説明する。


ファイルからのオブジェクトのロード

オブジェクトをロードするには、まず DirectMusicLoader8 オブジェクトを作成する。続いて、次のいずれかのメソッドを呼び出す。

  • DirectMusicLoader8.LoadBand
  • DirectMusicLoader8.LoadChordMap
  • DirectMusicLoader8.LoadCollection
  • DirectMusicLoader8.LoadSegment
  • DirectMusicLoader8.LoadStyle

目的のオブジェクトが含まれているファイルの、ファイル名またはフル パスのいずれかを渡す。

次のサンプル コードでは、現在のディレクトリにあるファイルからセグメントをロードしている。objDX は DirectX8 オブジェクトを表す。

Dim objDMLoader As DirectMusicLoader8
Dim objSeg As DirectMusicSegment8

Set objDMLoader = objDX.DirectMusicLoaderCreate
Set objSeg = objDMLoader.LoadSegment("Myseg.sgt")

「リソースからのオブジェクトのロード」も参照すること。


リソースからのオブジェクトのロード

リソースとして格納されたオブジェクトまたはメモリ内の別の場所に格納されたオブジェクトは、ファイル オブジェクトと同様にロードされる。「ファイルからのオブジェクトのロード」を参照すること。

次のメソッドはそれぞれ、モジュール名とリソース識別子をパラメータとして受け取り、適切なクラスのインスタンスを返す。

  • DirectMusicLoader8.LoadBandFromResource
  • DirectMusicLoader8.LoadChordMapFromResource
  • DirectMusicLoader8.LoadCollectionFromResource
  • DirectMusicLoader8.LoadSegmentFromResource
  • DirectMusicLoader8.LoadStyleFromResource

ローダーでは、次の種類のリソースが認識される。

文字列識別子 | メソッド
DMBAND | LoadBandFromResource
DMCHORD | LoadChordmapFromResource
DMCOLL | LoadCollectionFromResource
DMSEG | LoadSegmentFromResource
DMSTYLE | LoadStyleFromResource

ほかのオブジェクトによって参照されているオブジェクトは、最初にロードしなければならない。たとえば、スタイルへの参照を含むセグメントをロードする場合、セグメントを正しく演奏するには、スタイルが先にロードされていなければならない。

次のサンプル コードでは、実行可能ファイルに "DMSEG" リソースとして格納されている MIDI ファイルを、ロードおよび演奏する。loader は DirectMusicLoader8 オブジェクトを表し、perf は DirectMusicPerformance8 を表す。

Dim seg As DirectMusicSegment8
Set seg = loader.LoadSegmentFromResource("listen.exe", "CANYON.MID")
Call seg.Download(perf)
Call perf.PlaySegmentEx(SEG, 0, 0)


コンテナ

ここでは、C++ でのアプリケーション開発について説明する。DirectX for Visual Basic では、コンテナはサポートされない。


オブジェクト ディスクリプタの取得

ここでは、C++ でのアプリケーション開発について説明する。


キャッシュの管理

ここでは、C++ でのアプリケーション開発について説明する。


ガベージ コレクション

ここでは、C++ でのアプリケーション開発について説明する。


オブジェクトの設定

ここでは、C++ でのアプリケーション開発について説明する。


サウンドの再生

ここでは、DirectMusic のパフォーマンスの基本的な要素と、ソースからデータを取得して出力するために必要となる重要なメソッドを紹介する。

説明するトピックは、次のとおりである。

  • パフォーマンスの作成
  • セグメントの使い方
  • バンドの使い方
  • タイミング
  • 通知とイベントの処理


パフォーマンスの作成

パフォーマンス オブジェクトは再生全般を管理する。パフォーマンス オブジェクトは、次のタスクを実行する。

  • ポートとオーディオパスの管理
  • オーディオパスへのチャンネルのマッピング
  • セグメントの演奏と停止
  • メッセージのディスパッチ
  • タイミングの管理

ほとんどのアプリケーションは、DirectMusicPerformance8 オブジェクトを 1 つだけ使用するが、マスタ テンポやボリュームなどのパラメータの異なる複数のパフォーマンスを使用することもできる。

作成したパフォーマンスは、DirectMusicPerformance8.InitAudio の呼び出しによって初期化しなければならない。

InitAudio は、DirectSound8 オブジェクトをパフォーマンスに関連付けて、シンセサイザから出力されたサウンド データを DirectSound で管理できるようにする。DirectSound を単独で使用するアプリケーションでは、既存のオブジェクトを InitAudio に渡すか、このメソッドによって作成されたオブジェクトに変数を設定する。しかし、通常は、DirectSound8 オブジェクトにアクセスする必要はない。

InitAudio に渡さなければならない DMUS_AUDIOPARAMS 型に値を設定することによって、アプリケーションはシンセサイザの機能を要求したり、デフォルト以外のシンセサイザを設定できる。ほとんどのアプリケーションではこれを行う必要はなく、DMUS_AUDIOPARAMS.lValidData を 0 のままにしてデフォルトのシンセサイザと機能を要求する。

次のサンプル コードでは、パフォーマンスを作成し、初期化している。objDX は DirectX8 オブジェクトである。16 のパフォーマンス チャンネルと、ポート上で使用可能なすべての機能を持つ、デフォルトの標準オーディオパスを作成する。

Dim objDMPerformance as DirectMusicPerformance8
Dim audParams As DMUS_AUDIOPARAMS

Set objDMPerformance = objDX.DirectMusicPerformanceCreate
objDMPerformance.InitAudio Me.hWnd, DMUS_AUDIOF_ALL, audParams, _
     Nothing, DMUS_APATH_SHARED_STEREOPLUSREVERB, 16


セグメントの使い方

セグメントは、DirectMusic のパフォーマンスで演奏可能なデータの基本単位である。各セグメントは DirectMusicSegment8 オブジェクトによって表される。

セグメント オブジェクトは、次のいずれかの方法で作成できる。

  • DirectMusicLoader8.LoadSegment または DirectMusicLoader8.LoadSegmentFromResource メソッドを使って、DirectMusicSegment8 クラスをサポートするファイルまたはリソース オブジェクトをロードする。詳細については、「オーディオ データのロード」を参照すること。
  • DirectMusicStyle8.GetMotif メソッドを使用して、スタイルからモチーフを取得する。
  • DirectMusicComposer8 クラスのメソッドを使用して、実行時にアレンジまたはトランジションを作成する。「アレンジ用のプログラミング概要」および「トランジションの使い方」を参照すること。
  • DirectMusicSegment8.Clone メソッドを使用して、既存のセグメントのコピーを作成する。
  • DirectMusicBand8.CreateSegment メソッドを使用する。このメソッドにより、バンド チェンジの作成だけに使用される、特殊なセカンダリ セグメントが作成される。「プログラムによるバンド チェンジの実行」を参照すること。

セグメントは、パフォーマンスで異なる役割を果たす場合がある。常に必要なプライマリ セグメントは、サウンドトラックの主な内容を提供し、通常、制御セグメントとして機能する。セカンダリ セグメントはプライマリ セグメントと共に演奏され、サウンド エフェクトや短いテーマを提供する。特殊なタイプのセカンダリ セグメントとしてモチーフがあり、常に DirectMusic スタイル オブジェクトから取得される。

さらに、特殊な役割を持つ 3 種類のセグメントがある。

  • トランジション セグメント。実行時に DirectMusic コンポーザ オブジェクトによって作成される短い音楽のトランジションで、通常、あるセグメントから別のセグメントへ、またはセグメントから無音へ移行するプライマリ セグメントとして演奏される。
  • バンド セグメント。パフォーマンス内のさまざまなチャンネル用の一連の音色および音色セグメント。アプリケーションはバンド セグメントをセカンダリ セグメントとして演奏し、音楽を演奏するバンドに変更を加えることができる。
  • テンプレート セグメント。コード進行、グルーブ レベル、および装飾などのガイドとして、実行時にスタイルやコードマップと共に組み合わされ、音楽を形成する。

セグメントの再生は、DirectMusicPerformance8 オブジェクトで制御され、DirectMusicPerformance8.PlaySegmentEx の呼び出しで開始される。

パフォーマンス内では、ただ 1 つのプライマリ セグメントを演奏できる。再生の目的でプライマリ セグメントを挿入する場合は、現在演奏されているセグメントが終わった後にそのセグメントを演奏するように指定したり、現在のプライマリ セグメントを置き換えることができる。

一方、セカンダリ セグメントはプライマリ セグメント上で演奏され、任意の数のセカンダリ セグメントを同時に演奏できる。

通常、セカンダリ セグメントはプライマリ セグメントのパフォーマンスを変更しない。たとえば、セカンダリ セグメントは、プライマリ セグメントのスタイルに影響を与えずに、別のスタイルに基づくことができる。ただし、セカンダリ セグメントを制御セグメントとして指定できる。この場合、セカンダリ セグメントは、通常プライマリ セグメントで処理される特定のタスクを実行する。

セグメントの詳細については、次のトピックを参照すること。

  • セグメントの状態
  • 制御セグメント
  • 自己制御セグメント
  • ウェーブ セグメント

「セグメントのタイミング」も参照すること。


セグメントの状態

セグメントを演奏する場合、オーディオパス、反復、開始ポイントなど、そのセグメントのパラメータは DirectMusicSegmentState8 オブジェクトで表されるセグメント状態オブジェクトに格納される。パラメータは、セグメントのそのインスタンスについてのみ有効である。DirectMusicSegment8 のメソッドを使用して、セグメントに対して行った変更は、DirectMusicPerformance8.PlaySegmentEx の呼び出しによって作成される新しいセグメント状態に反映される。


制御セグメント

セカンダリ セグメントは制御セグメントとして指定することができる。この場合、セカンダリ セグメントは DirectMusicPerformance8.GetCommand などの特定の呼び出しに応答するタスクを実行し、現在のテンポ、コード、グルーブ レベルなど、音楽のいくつかの面を制御する。

デフォルトでは、プライマリ セグメントは制御セグメントである。ただし、DMUS_SEGF_CONTROL フラグを DirectMusicPerformance8.PlaySegmentEx に渡すことによって、セカンダリ セグメントを制御セグメントとして指定できる。詳細については、「CONST_DMUS_SEGF_FLAGS」を参照すること。

セカンダリ セグメントが制御セグメントである場合も、プライマリ セグメントは制御データの代替ソースとして機能し続ける。たとえば、セカンダリ制御セグメントにテンポ トラックが含まれていない場合に、プライマリ セグメントに含まれている場合は、プライマリ セグメントのテンポが使用される。


自己制御セグメント

自己制御セグメントは、自己制御セグメントから制御情報をコピーする制御セグメントからの制御情報を無視する。たとえば、セグメントにコマンド トラックがある場合、制御セグメントで設定されたグルーブ レベルではなく、独自のグルーブ レベルを使用できる。

セグメントは、次のように、各トラックについて制御情報を取得する場所を定義できる。

  • 制御セグメントのトラックから。これはデフォルトの動作である。
  • プライマリ セグメントのトラックから。プライマリ セグメントが制御セグメントであるかどうかは関係ない。
  • 同じセグメントのトラックから。

セグメントは、オーサーによって自己制御セグメントとして構成される。DirectX for Visual Basic では、アプリケーションによるトラック構成はサポートされない。


ウェーブ セグメント

DirectMusic ローダーは、オーディオ圧縮マネージャ (ACM) でサポートされているフォーマットの圧縮されたウェーブフォーム オーディオ ファイル、および非圧縮ウェーブ ファイルをロードできる。

ウェーブ ファイルに基づくセグメントは、ほかのセグメントと同様に演奏される。このようなセグメントは、メッセージとしてパフォーマンスに渡され、常にオーディオパスのチャンネル 0 で演奏される。ウェーブについてはノートとは異なる意味の合成が行われるが、ウェーブもシンセサイザに渡されて、MIDI コントローラで操作できる。

次のサンプル コードでは、ピッチ チェンジ MIDI メッセージをデフォルトのオーディオパスのチャンネル 0 に送信している。dmp は DirectMusicPerformance8 オブジェクトである。ピッチの変更は、そのオーディオパスで再生されるすべてのウェーブに影響する。

Private Sub sldrPitch_Change()

    Dim hi As Byte, lo As Byte

    ' 値を 7 ビット バイトに分割する。スライダから返される値は
    ' 0 ～ 16383 の範囲である。

    hi = Fix(sldrPitch.Value / 128)
    lo = CByte(sldrPitch.Value And 127)

    ' ピッチ ベンド メッセージを送信する。

    Call dmp.SendMIDIPMSG(0, DMUS_PMSGF_REFTIME, 0, &HE0, _
        lo, hi)

End Sub

注 アプリケーションが複数のオーディオパスを使用する場合、この例に示されている手法が機能しないことがある。DirectX for Visual Basic では、アプリケーションで作成されたメッセージを特定のオーディオパスに送信する方法はない。パフォーマンス チャンネル 0 は、オーディオパスごとに、シンセサイザの異なるチャンネルにマップされるので、あるパスでの MIDI コントローラの変更はほかのパスに影響しない。詳細については、「アプリケーションで作成されたメッセージ」を参照すること。

ウェーブもまた DirectMusic Producer ファイルに埋め込んで、さまざまなバリエーションのあるスタイルのように動作させることができる。例については、AudioScripts サンプル アプリケーションを参照すること。このサンプルの ScriptDemoBaseball.spt スクリプトは、ボタンがクリックされるたびに物売りの叫び声のバリエーションを再生する。

セグメント (.sgt) ファイルのウェーブは、再生する前にダウンロードする必要がある。セグメントのバンドをダウンロードすると、これらのウェーブもダウンロードされる。詳細については、「バンドのダウンロードとアンロード」を参照すること。


バンドの使い方

バンドとは、セグメントまたはスタイル内の特定のパートに割り当てられた一連の音色である。演奏時に各音色トラックは、次の情報を保存しているパフォーマンス チャンネルにマップされる。

  • MIDI ボリューム。
  • MIDI パン。
  • 転調。この値が 0 でない場合、チャンネル上の音楽のノートは、音色に合わせて自動的に転置される。
  • 音色の MIDI パッチ番号。バンク セレクトの MSB と LSB も含まれる。
  • 音色のロード元となる DLS コレクションへの参照。デフォルトの DLS コレクションは、スタンダード General MIDI コレクションである。

セグメントとスタイルは常に、少なくともデフォルト バンドと呼ばれる 1 つのバンドによって構成される。スタイルには、追加のバンドを含めることができる。セグメントまたはスタイルをロードするときに、デフォルト バンドおよびその他のバンドは、どちらも自動的にロードされる。ただし、どんなバンドを使用する場合でも、バンドの音色用に DLS データをダウンロードしなければならない。

DirectMusicStyle8.GetDefaultBand メソッドを使って、デフォルト バンドを表すオブジェクトを取得できる。スタイルにオーサリングされたその他のバンドは、DirectMusicStyle8.GetBand メソッドを使って、検索および取得することができる。バンドは、ほかのスタイル ファイルやバンド ファイルからも取得できる。DirectMusicBand8 オブジェクトを取得した後、このバンドにアクセスし、デフォルトのバンドを置き換えることもできる。

バンドは、ほかのオブジェクトと同様にロードされる。詳細については、「オーディオ データのロード」を参照すること。

バンドの詳細については、次のトピックを参照すること。

  • バンドのダウンロードとアンロード
  • プログラムによるバンド チェンジの実行
  • 確実なタイミングでのバンド チェンジ
  • カスタム音色による MIDI ファイルの演奏


バンドのダウンロードとアンロード

バンドを使用するには、まず参照する音色をパフォーマンスにダウンロードしなければならない。この手順により、音色がパフォーマンス チャンネルに割り当てられ、シンセサイザに DLS データがダウンロードされる。

デフォルトでは、使用するバンドのダウンロードはアプリケーションが行う。ただし、バンドの自動ダウンロードを有効にすることもできる。

バンドのダウンロードにより、パフォーマンスがバンドを利用できるようになるが、プログラム チェンジは行われない。プログラム チェンジは、セグメントのバンド トラックで生成されるメッセージに応じて実行される。このメッセージは、一般的にはセグメント ファイルにオーサリングされる。実行時にプログラム チェンジを行う方法については、「プログラムによるバンド チェンジの実行」を参照すること。

バンドのダウンロードとアンロードを実装する方法については、次のトピックを参照すること。

  • バンドの自動ダウンロード
  • バンドの手動ダウンロード
  • パッチの競合
  • バンドのアンロード


バンドの自動ダウンロード

自動ダウンロードが有効な場合、バンドに含まれるセグメントがキューに格納されるときに、バンドの音色がダウンロードされる。セグメントが停止されると、同じ音色を使用しているほかのセグメントを直ちにキューに入れて演奏するか、現在演奏中でない限り、音色は自動的にアンロードされる。

自動ダウンロードは、セグメントのタイミングが重要でないときにだけ使用するべきである。音色のロードとアンロードを繰り返すと時間がかかり、複雑なオーディオ環境では、重大なパフォーマンスの低下が発生する場合がある。

自動ダウンロード メカニズムの一部である自動アンロードでも、望んでいない結果となる場合がある。たとえば、チャンネルの音色を変更する短いセカンダリ セグメントを演奏する場合を考える。セカンダリ セグメントが開始されるときに、音色が自動的にダウンロードされ、既存の音色に置き換えられる。セカンダリ セグメントが終了すると、音色は自動的にアンロードされ、その結果、チャンネルに音色がなくなり、そのチャンネルは無音を再生する。

DirectMusicPerformance8.SetMasterAutoDownload メソッドを使って、パフォーマンス全体でバンドの自動ダウンロードを有効にしたり、DirectMusicSegment8.SetAutoDownloadEnable メソッドを使って、セグメントごとに自動ダウンロードを有効にすることができる。


バンドの手動ダウンロード

次のいずれかの方法を使うと、バンドを手動でダウンロードすることができる。

  • DirectMusicSegment8.Download を呼び出し、セグメントのバンドをオーディオパスまたはパフォーマンスのどちらかにダウンロードする。
  • ファイル、リソース、または DirectMusicStyle8 オブジェクトから DirectMusicBand8 オブジェクトを取得し、その DirectMusicBand8.Download メソッドを呼び出す。


パッチの競合

異なるセグメントのバンドを同じポートにダウンロードすると、バンド内の音色によって、以前にダウンロードしたバンドのデータが上書きされる場合がある。

たとえば、セグメント A がピアノをパッチ番号 1 に割り当てるバンドを使用し、セグメント B がバンジョーを同じパッチに割り当てるバンドを使用するとする。アプリケーションは、最初にセグメント A、次にセグメント B について DirectMusicSegment8.Download を呼び出す。バンドが異なるオーディオパスにダウンロードされた場合でも、音色データは同じシンセサイザにダウンロードされるので、パフォーマンス チャンネルのすべてのノートは、バンジョーによって演奏されるパッチ番号 1 にマップされる。

コンテンツをオーサリングするときには、このような潜在的なパッチの競合を考慮する必要がある。複数のセグメントで、同じパッチ番号の異なる音色を使用するべきではない。


バンドのアンロード

バンドはメモリを消費するため、使用しなくなったバンドはアンロードするべきである。自動ダウンロードを有効にしている場合は、セグメントが終了したときに、セグメントに関連付けられているバンドが自動的にアンロードされる。アンロードされない場合は、対応する Download メソッドでダウンロードされた音色について、DirectMusicSegment8.Unload または DirectMusicBand8.Unload メソッドを呼び出す。

DirectMusicPerformance8.CloseDown メソッドでも、ダウンロードされた残りの音色がアンロードされる。


プログラムによるバンド チェンジの実行

通常は、ロードされたセグメントのバンド トラックによって、プログラム チェンジが実行される。ただし、手動で行うこともできる。

まず、DirectMusicBand8.CreateSegment を使用してセグメントを作成し、DirectMusicPerformance8.PlaySegmentEx を呼び出してそのセグメントを演奏する。通常は lFlags パラメータ内の DMUS_SEGF_MEASURE または DMUS_SEGF_GRID を使って、適切な境界でバンド チェンジが有効になるよう保証する。

パフォーマンスは、一度に複数のバンドの音色を演奏することができる。たとえば、アプリケーションが 1 つのバンドを使ってプライマリ セグメントを演奏しているときに、別のバンドを持つスタイルのモチーフを演奏する場合を考える。2 つのバンドの音色が異なるパフォーマンス チャンネルにマップされている限り、競合は発生しない。ただし、通常、モチーフ セグメントは独自のバンド トラックを持たない。したがって、最初にバンド セグメントを作成してから演奏しなければ、モチーフのパフォーマンス チャンネルからは音が出ない


確実なタイミングでのバンド チェンジ

バンド セグメントを演奏するときに重要な問題となるのは、スタイル トラックで演奏されるノートのタイミングのばらつきである。たとえば、小節 1 の 1 拍目のノートが、実際の拍の境界よりわずかに進んだり遅れたりする場合がある。バンド セグメントではこの状況を認識していないので、いくつかのノートが間違った音色で演奏される場合がある。

この問題を避けるために、アプリケーションはバンド セグメントを早めにキューに格納するべきである。たとえば、スタイル セグメントの styleSeg とバンド セグメントの bandSeg があり、パフォーマンス (perf) の次の小節境界で、スタイル セグメントとバンド セグメントの両方を演奏する場合を考える。スタイルには、セグメントの開始タイムよりも、最大 30 ティック (ミュージック タイムで) 早く開始される可能性のあるノートが含まれていることがわかっている。次のサンプル コードでは、バンド セグメントがスタイル セグメントよりも 31 ティック前に演奏されることが保証されている。したがって、すべての音色は、ノートが演奏される前に適切に設定される。

' まず、次の小節のタイムを取得して、
' ミュージック タイムに変換する。

Dim ctResolved As Long
Dim mtResolved As Long

ctResolved = perf.GetResolvedTime(ctResolved, DMUS_SEGF_MEASURE)
mtResolved = perf.ClockToMusicTime(ctResolved)

' バンド セグメントを、小節境界の 31 ティック前に演奏する。

mtResolved = mtResolved - 31
Call perf.PlaySegmentEx(bandSeg, 0, mtResolved)

' スタイル セグメントを小節境界で演奏する。

Call perf.PlaySegmentEx(styleSeg, DMUS_SEGF_MEASURE, 0 )

注 セグメントで演奏されるノートにばらつきがない場合 (たとえば、MIDI ファイルからロードされたセグメントの場合) は、同時に演奏されるバンド セグメントのタイミングについて注意する必要はない。デフォルトでは、すべてのバンド セグメントは 1 ティック早く開始される。


カスタム音色による MIDI ファイルの演奏

MIDI ファイルを演奏する場合、デフォルトでは、Gm.dls ファイルに含まれる Roland GM/GS Sound Set の音色が使用される。ただし、MIDI ファイルを演奏するときに、任意の DLS コレクションの音色を使用できる。

ほかのコレクションの音色を使って MIDI ファイルを演奏するには、MIDI ファイルに基づいて、コレクションをロードし、セグメントに関連付ける。次に、ほかのセグメントの場合と同様に、コレクションをダウンロードする。

次のサンプル コードでは、DLS コレクションをロードし、dmSeg によって表される DirectMusicSegment8 オブジェクトに接続し、DirectMusicPerformance8 オブジェクト dmPerf のデフォルトのオーディオパスにダウンロードしている。dmLoader は DirectMusicLoader8 オブジェクトである。

Dim dmColl As DirectMusicCollection8

Set dmColl = dmLoader.LoadCollection("boids.dls")
dmSeg.ConnectToCollection dmColl
dmSeg.Download dmPerf.GetDefaultAudioPath

MIDI セグメントにカスタム コレクションを付加するときに、GM コレクションへの接続は切断されない。たとえば、パッチ番号が 12 の 1 つの音色を含むコレクションをロードし、これをセグメントに接続する場合、12 以外のパッチ番号を持つ MIDI チャンネルでは、GM コレクションの適切な音色を使って演奏が続けられる。

コレクションの詳細については、「音色コレクションの使い方」を参照すること。


タイミング

ここでは、DirectMusic のさまざまなタイミングの概要について説明する。説明するトピックは、次のとおりである。

  • マスタ クロック
  • クロック タイムとミュージック タイム
  • テンポの変更
  • 準備時間
  • 遅延時間とバンパー時間
  • セグメントのタイミング


マスタ クロック

ここでは、C++ でのアプリケーション開発について説明する。DirectX for Visual Basic では、アプリケーションは別のマスタ クロックを選択することはできない。


クロック タイムとミュージック タイム

DirectX for Visual Basic では、マスタ クロックによって返されるタイムは Long であり、およそ 1 ミリ秒の単位で表される。DirectMusicPerformance8.GetClockTime によって返される値は、任意の開始タイム以降に経過した時間である。

ミュージック タイムも Long であり、時間の絶対的な測定値ではなく、テンポに基づく相対値である。クロックは、パフォーマンスが初期化されるときに開始され、4 分音符あたり 768 の時間が経過する。現在のタイムは、DirectMusicPerformance8.GetMusicTime を使って取得することができる。

パフォーマンスで 2 種類のタイムを変換するには、DirectMusicPerformance8.MusicToClockTime および DirectMusicPerformance8.ClockToMusicTime メソッドを使用する。

DirectMusicPerformance8.PlaySegmentEx の呼び出しによってセグメントがキューに格納され、開始タイムがクロック タイムで与えられる場合、DirectMusic は開始タイムをミュージック タイムに変換しなければならない。その時点でプライマリ セグメントが演奏されていない場合、このタイムは現在のテンポに従って直ちにミュージック タイムに変換される。ほかのプライマリ セグメントが演奏されている場合は、挿入されたセグメントの開始タイムに達した時点で、その開始タイムがミュージック タイムに変換される。

セグメントの演奏が開始される前にテンポが変更された場合は、開始タイムが影響を受ける可能性があり、セグメントが希望した境界で開始されない場合がある。前者の状況では、直ちにミュージック タイムへの変換が行われる。テンポの速度が上昇した場合は (基準タイムでの) 開始タイムは早まり、テンポの速度が低下した場合は遅れる。後者の状況では、開始タイムに変換が行われるので、テンポの変更が発生すると、正確な分解能の境界でセグメントが始まらないことを意味する。たとえば、セグメントがある小節境界 (PlaySegmentEx の IFlags パラメータで指示) で開始される場合、クロック タイムでの実際の開始タイムは、セグメントがキューに格納されるときに計算される。その後でテンポが変更されると、小節境界が計算したタイムどおりにならない可能性がある。

プライマリ セグメントが DMUS_SEGF_QUEUE フラグと共に PlaySegmentEx に渡されるときに (CONST_DMUS_SEGF_FLAGS を参照)、startTime パラメータは無視され、セグメントは、既に開始タイムが変換されているプライマリ セグメントの後で演奏されるように、キューに格納される。これは、基準タイムを指定して現在キューに置かれているセグメントが、DMUS_SEGF_QUEUE セグメントに割り込む可能性があることを意味する。

たとえば、3 つのセグメントがあり、それぞれの長さが 10 秒であるとする。セグメント A を、今から 5 秒後に演奏するようにキューに格納する。現在演奏されているプライマリ セグメントはないため、開始タイムは直ちにミュージック タイムに変換される。6 秒経過した時点で、セグメント B を 20 秒から演奏するようにキューに格納する。この場合、既に音楽が演奏中で、テンポが変更されている可能性があるため、ミュージック タイムへの変換はすぐには行われない。次に、DMUS_SEGF_QUEUE フラグを設定したセグメント C を、セグメント A が終了しだい、つまり 15 秒から演奏するようにキューに格納する。20 秒の時点で、セグメント B の演奏が開始され、セグメント C が中断される。


テンポの変更

パフォーマンスのテンポは、DirectMusic で使用される 2 種類のタイムの変換を指示し、音楽境界のイベントの分解能を制御する(「クロック タイムとミュージック タイム」を参照すること)。通常、制御セグメントのテンポ トラックがテンポを管理するが、アプリケーションで動的にテンポを設定することもできる。

これを実行する方法は 2 つある。マスタ テンポを設定する方法と、テンポ メッセージを送信する方法である。

マスタ テンポは、パフォーマンスのすべてのテンポに乗算する係数である。たとえば、0.75 のパラメータで DirectMusicPerformance8.SetMasterTempo を呼び出してマスタ テンポを設定し、1 分間に 120 拍のテンポを持つセグメントを演奏する場合、セグメントは 90 のテンポで演奏される。

DirectMusicPerformance8.SendTempoPMSG メソッドを使ってテンポを送信すると、メッセージのスタンプに指定されたタイムにテンポが変更される。新しいテンポは、別のテンポ メッセージが送信されるか、テンポが制御セグメントによって変更されるまで有効である。テンポの値は、マスタ テンポによって変更することができる。

次の呼び出しでは、テンポは直ちに 1 分間につき 100 拍に設定される。perf は DirectMusicPerformance8 オブジェクトを表す。lTime パラメータに 0 を渡して、メッセージを直ちに送信するように指定する場合は、DMUS_PMSGF_REFTIME フラグも設定しなければならない。

Call perf.SendTempoPMSG(0, DMUS_PMSGF_REFTIME, 100)


準備時間

セグメントを演奏するときに、パフォーマンスはセグメントのトラックを繰り返し呼び出す。この呼び出しにより、1 秒の何分のいくつかの指定された時間範囲分のメッセージが生成される。これらのメッセージは、これまでの呼び出しで生成されたメッセージの後ろに挿入される。デフォルトでは、およそ 1 秒分のメッセージが、いつでもキューにある。

パフォーマンスがメッセージを演奏するようにトラックに要求するごとに、現在のタイムに準備時間を加算して、呼び出しの終了タイムが計算される。現在のタイムが 10,000 ミリ秒 (または、等価な REFERENCE_TIME 単位) で、準備時間がデフォルトで 1000 ミリ秒である場合、終了タイムは 11,000 となる。つまり、11,000 までの演奏分の新しいメッセージをすべて準備して、キューに格納しなければならない。

キューのサイズは、DirectMusicPerformance8.SetPrepareTime メソッドを呼び出して変更することができる。現在のサイズは、DirectMusicPerformance8.GetPrepareTime を使って取得することができる。

ほとんどのアプリケーションでは、デフォルトの準備時間を変更する必要はない。ここで説明した処理は、アプリケーションからは認識されていない。ただし、アプリケーションは DirectMusicPerformance8.PlaySegmentEx に DMUS_SEGF_AFTERPREPARETIME フラグを渡すことができるので、準備時間の概念を理解しておくと役立つ。

このフラグを使用しない場合、セグメントの開始タイムを "現在" に設定すると、パフォーマンスは現在キューに格納されているメッセージをすべて無効にする。この時点で有効なままのトラック (たとえば、新しいプライマリ セグメントの導入にかかわらず、演奏が続けられるセカンダリ セグメントのトラック) は、新しいセグメントによる環境の変化を考慮して、メッセージを再送信しなければならない。これによって、追加の処理が発生し、好ましくない結果になる場合もある。

DMUS_SEGF_AFTERPREPARETIME フラグを使用して、現在キュー内にあるすべてのメッセージが処理され、ポート バッファに渡されるまで、セグメントを演奏しないことを指定できる。タイム 10,000 までのメッセージがキューにあり、現在のタイムが 9,000 ms の場合、演奏用にキューに格納され、DMUS_SEGF_AFTERPREPARETIME フラグが設定されたセグメントは、ちょうど 10,000 ミリ秒後に演奏を開始する。

詳細については、「セグメントのタイミング」を参照すること。「遅延時間とバンパー時間」の図も参照すること。


遅延時間とバンパー時間

遅延時間とは、ポートが メッセージを受け取ってから、演奏すべき十分なウェーブが合成されるまでの遅れを意味する。DirectMusicPerformance8.GetLatencyTime メソッドは、現在のタイムにパフォーマンスの遅延時間を加算した全体の時間を取得する。この値は、ポートの遅延時間クロックによって返される最大の値である。

バンパーとは、イベントがポート バッファに置かれてから、ポートがそのイベントの処理を開始するタイムまでの、コードを実行するために割り当てられた時間である。デフォルトでは、バンパーの長さは 50 ミリ秒 (ms) である。アプリケーションは、DirectMusicPerformance8.SetBumperLength メソッドを使ってこの値を変更したり、DirectMusicPerformance8.GetBumperLength を呼び出して現在の値を取得することができる。

ここでは、遅延時間とバンパー時間を結合する方法を示す。あるイベントが 10,000 ミリ秒の時点で演奏されると仮定する。このポートの遅延時間は 100 ミリ秒であること、およびバンパー時間の長さはデフォルトの 50 ミリ秒であることがわかっている。そのため、パフォーマンスは 9,850 ミリ秒の時点でこのメッセージをポート バッファに置く。

ポート バッファに置かれたメッセージは、もはやパフォーマンスに所属していないため、DirectMusicPerformance8.Invalidate または DirectMusicPerformance8.StopEx メソッドを使っても、演奏を止められない点に注意すること。無効にできる最初のメッセージは、現在のタイムに遅延時間とバンパー時間を加えたタイムと同じか、それ以降のタイム スタンプを持つ。DirectMusicPerformance8.GetQueueTime メソッドを使うと、この値を取得することができる。

次の図は、さまざまなメソッドで取得される、タイムと継続時間の関係を示している。現在のタイムは左側に示されている。右側が、メッセージの準備が完了する最終タイムである。準備時間はいつでも、キューにあるメッセージの合計の長さの近似である。

図に示すメソッドは C++ API のものであるが、DirectX for Visual Basic でもほとんど同じ名前が使用されている。図の GetTime メソッドは、DirectMusicPerformance8.GetClockTime とほぼ同じである。


セグメントのタイミング

ここでは、セグメントの演奏のタイミングに関するさまざまな面について説明する。

セグメントのタイムとパフォーマンスのタイムとの関係を明確にするために、ここでは次の用語を使用する。

開始ポイント
セグメントの開始タイムになりうるセグメント内の最初のポイント。デフォルトの場合、この値は 0 で、セグメントの先頭を示す。ただし、この値はアプリケーションで変更できる。
セグメントの開始タイム
サウンドの生成が開始されるセグメント内のポイント。このタイムは通常開始ポイントと同じであるが、開始ポイントが意図的に過去の演奏タイムに揃えられている場合は、遅くすることもできる。
演奏タイム
新しいセグメントの開始ポイントがキューに入れられるパフォーマンス内のポイント。DirectMusic API では、このタイムは開始タイムと呼ばれることもある。
開始マーカー
セグメント内の有効な開始タイムを示すマーカー。
演奏マーカー
制御セグメント内で、別のセグメントの開始ポイントをキューに入れることができるポイントを示すマーカー。

注 開始マーカーおよび演奏マーカーは、オーサーによってセグメントのマーカー トラックに配置され、アプリケーションで変更することはできない。

セグメントは、通常、最初から演奏される。DirectMusicSegment8.SetStartPoint メソッドを使用して、別のポイントからセグメントを開始することもできる。この開始ポイントは、セグメントを演奏するときは常に使用される。

DirectMusicSegment8.SetRepeats を使ってリピート回数を設定した場合、DirectMusicSegment8.SetLoopPoints を呼び出してループを定義しなければ、セグメント全体がその回数だけ反復される。

演奏タイムは、DirectMusicPerformance8.PlaySegmentEx の 2 つのパラメータによって決定される。

  • startTime パラメータは、セグメントの演奏を開始できる、最も早いタイムを設定する。startTime が 0 の場合は、可能な限り早いタイムとなる。セグメントが演奏される実際のタイムは、セグメントの種類によって異なる。プライマリ セグメントまたは制御セグメントの場合、最も早い演奏タイムはキュー (またはフラッシュ) 時間である。制御以外のセカンダリ セグメントの場合、最も早い演奏タイムは遅延時間後である。キュー時間と遅延時間の詳細については、「遅延時間とバンパー時間」を参照すること。
  • lFlags パラメータは、最も早い演奏タイムの後、どれくらいすぐにセグメントの演奏を実際に開始するかを指定する。通常、新しいプライマリ セグメント、トランジション、またはモチーフを開始する前に、リズムの適切なポイント待つ。次の CONST_DMUS_SEGF_FLAGS 列挙型の 1 つ以上を設定することにより、遅延を制御する。

セグメントを過去のタイムに揃える

セグメントの開始タイムを制御セグメントの次のグリッド、拍、または小節に揃える代わりに、セグメントの演奏をすぐに開始し、現在のセグメントのリズムに合わせたい場合がある。このようにするには、セグメントの開始ポイントのキューを既に経過したリズム境界に与える。キューを与えたセグメントのリズムは、現在のセグメントに揃えられ、新しいセグメントは直ちに演奏を開始できる。

過去のセグメントにキューを与えるには、DMUS_SEGF_ALIGN フラグを使用する。適切なリズム境界でセグメントの開始ポイントにキューを与えるには、DMUS_SEGF_GRID、DMUS_SEGF_BEAT、または DMUS_SEGF_MEASURE のいずれかを追加する。この代わりに、DMUS_SEGF_MARKER を使用して、開始ポイントを制御セグメントの最後に演奏された演奏マーカーに揃えることもできる。

開始ポイントが過去である場合、セグメントの開始タイムが現在または将来になるように調整しなければならない。パフォーマンスは、次の規則に従って、セグメントの開始タイムを決定する。いずれの場合も、"次" とは "次に可能" であることを意味する。つまり、セグメントの、過去ではない部分にあるという意味である。

  • 開始マーカーが、キューを与えられたセグメントの、指定されたタイプの次の分解能境界よりも前にある場合、そのセグメントの開始タイムはそのポイントになる。
  • 有効な開始マーカーがない場合、セグメントの開始タイムはキューを与えられたセグメントの次の開始分解能境界になる。これは次のいずれかのフラグで指定される。
    DMUS_SEGF_VALID_START_BEAT
    セグメントの開始タイムを次の拍にする。
    DMUS_SEGF_VALID_START_GRID
    セグメントの開始タイムを次のグリッドにする。
    DMUS_SEGF_VALID_START_TICK
    セグメントの開始タイムを最も早いポイントにする。
  • 有効な開始マーカーがなく、開始分解能フラグが指定されていない場合、セグメントの開始タイムは次の演奏分解能境界になる。これは、DMUS_SEGF_GRID、DMUS_SEGF_BEAT、または DMUS_SEGF_MEASURE フラグで指定される。これらのフラグがいずれも存在しない場合、セグメントの開始タイムは即時になる。

演奏マーカーと開始マーカーによって、セグメント、特にモチーフに柔軟にキューを与えることができる。モチーフが、プライマリ セグメントの小節の先頭で演奏を開始するときに最適に演奏されるように作成されているとする。このモチーフに DMUS_SEGF_MEASURE フラグでキューを与えると、次の小節境界に達して、モチーフが演奏されるまでに大幅な遅延が発生する場合がある。しかし、DMUS_SEGF_ALIGN フラグを追加すると、リズムを乱すことなく、すぐにモチーフの演奏を開始できる。DMUS_SEGF_MARKER フラグを追加すると、小節、拍、またはグリッドだけでなく、制御セグメント内の適切な境界でモチーフを演奏できるようになる。

テンポの変更によってセグメントの開始タイムが受ける影響については、「クロック タイムとミュージック タイム」を参照すること。

次の図は、DMUS_SEGF_MEASURE、DMUS_SEGF_ALIGN、および DMUS_SEGF_VALID_START_BEAT の各フラグを使ってキューに入れられたセグメントのタイミングを決定する過程を示している。縦の実線は小節の境界を示し、点線は拍の境界を示す。セグメントの開始ポイントは、現在のプライマリ セグメントの前にある小節境界に揃えられる。セグメントの開始タイムは、未解決の演奏タイムの後に挿入されているセグメントの最初の拍になる。

論理的なタイムと実際のタイム

一部のイベントは、論理的なタイムと実際のタイムの両方を持っている。実際のタイムはイベントが発生するときであり、論理的なタイムはイベントが属する音楽的な位置を表す。

たとえば、セグメントは、拍の開始に属するプログラム チェンジを含む場合がある。この拍の開始は論理的なタイムである。しかし、拍のノートが演奏される前にプログラム チェンジが行われるようにしたいので、これよりも少し早い物理的なタイムを割り当てる。

セグメントが論理的なタイム (同じ拍の開始) にループする場合、プログラム チェンジも行われる。


通知とイベントの処理

アプリケーションでパフォーマンス イベントに応答しなければならない場合がある。たとえば、セグメントの終了に到達したことを知る必要がある場合や、グラフィックスを音楽の拍に同期させたい場合がある。特定のタイプのイベントが発生したときに、そのことを通知するよう DirectMusic に指示して、必要な情報を取得することができる。

注 パフォーマンス通知と DirectSound のバッファ通知を混同してはならない。DirectSound のバッファ通知は、バッファに対して直接ウェーブ データをストリーミングするアプリケーションでのみ使用される。「再生バッファの通知」および「キャプチャ バッファの通知」を参照すること。

通知を受けたいイベントの種類を指定するには、イベントの種類ごとに一度だけ DirectMusicPerformance8.AddNotificationType メソッドを呼び出す。次のサンプル コードでは、DirectMusic にセグメント イベントを要求している。perf は DirectMusicPerformance8 オブジェクトである。イベントの種類 (セグメントの開始やセグメントの終了など) は、通知メッセージから得られる。

Call perf.AddNotificationType(DMUS_NOTIFY_ON_SEGMENT)

通知は、DMUS_NOTIFICATION_PMSG メッセージ タイプの形式で送られる。Sub Main で DirectMusicPerformance8.GetNotificationPMsg メソッドを呼び出して、保留中の通知メッセージをポーリングすることができる。また、メッセージが保留中のときに、DirectMusic に別のスレッドでイベント オブジェクトを通知させることもできる。

DirectMusic にイベントを通知させるには、DirectX8.CreateEvent を使用してイベント ハンドルを取得し、このハンドルを DirectMusicPerformance8.SetNotificationHandle に渡す。CreateEvent に渡すモジュールは DirectXEvent8 クラスを実装し、イベントを通知するときに DirectMusic によって呼び出される DirectXEvent8.DXCallback メソッドの実装を提供する必要がある。

次のサンプル コードでは、frmMain というフォーム モジュールの通知を設定している。

' DX は DirectX8 オブジェクトを表し、perf は DirectMusicPerformance8 オブジェクトを表す。

Dim hEvent As Long
hEvent = DX.CreateEvent(frmMain)
Call perf.SetNotificationHandle(hEvent)

フォーム モジュールには、セグメントが演奏を終了したことを示すメッセージを処理するコードが含まれる。

Implements DirectXEvent8

Private Sub DirectXEvent8_DXCallback(ByVal eventid As Long)

  Dim GotMSG As Boolean
  Dim PMsg As DMUS_NOTIFICATION_PMSG

  Do
    GotMSG = gobjDMPerformance.GetNotificationPMSG(PMsg)
    If GotMSG Then
      If PMsg.lNotificationOption = DMUS_NOTIFICATION_SEGEND Then

        ' セグメントの演奏が終了しているので、処理を実行する。
        .
        .
        .
      End If
    End If
  Loop Until Not GotMSG

End Sub

アプリケーションのメイン ループで、イベントを作成して通知メッセージを取得する必要はない。DirectMusicPerformance8.AddNotificationType メソッドを呼び出して通知を要求している場合、メッセージはパフォーマンスによって送信され、DirectMusicPerformance8.GetNotificationPMsg の呼び出しで取得することができる。

イベントが通知される場合、またはループで GetNotificationPMsg を呼び出す場合は、複数のメッセージを待機することができる。すべての通知を確実に受け取るには、False が返されるまで GetNotificationPMsg の呼び出しを繰り返す。

同じタイム スタンプを持つメッセージが複数ある場合、これらのメッセージはキューに格納されるときに特定の順序にはならない。


パフォーマンス パラメータ

DirectX for Visual Basic では、DirectMusicPerformance8 および DirectMusicSegment8 のさまざまなメソッドを使って、パフォーマンス パラメータを設定および取得できる。

変更されたパラメータにパフォーマンスを直ちに応答させるには、アプリケーションで DirectMusicPerformance8.Invalidate メソッドを使って、キューからメッセージをフラッシュする。このメソッドにより、すべてのトラックは指定したポイント以降のメッセージを再送信する。


トラック パラメータの設定と取得

DirectMusicPerformance8 および DirectMusicSegment8 のメソッドのいくつかでは、通常は制御セグメントの特定のトラックでパラメータを設定または取得することができる。ただし、DirectX for Visual Basic を使用するアプリケーションは、これらのトラックについて考慮する必要はない。これらのメソッドは、低レベルでの動作についての知識がなくても使用することができる。


トラックの識別

ここでは、C++ でのアプリケーション開発について説明する。


トラック パラメータの無効化と有効化

DirectMusicSegment8.SetTempoEnable および DirectMusicSegment8.SetTimeSigEnable メソッドを使うと、制御セグメントによるテンポと拍子記号の設定を無効にすることができる。たとえば、動的にテンポを設定して、プライマリ セグメントにテンポを変更させたくない場合などに使用できる。

SetTempoEnable を使うと、制御セグメントでないセグメントにもテンポ メッセージを送信させることもできる。また、SetTimeSigEnable を使って、セカンダリ セグメントに拍子記号メッセージを送信させることもできる。詳細については、「制御セグメント」を参照すること。


グローバル パラメータの設定と取得

DirectMusicPerformance8 クラスには、パフォーマンス全体に影響するグローバル パラメータを設定および取得するための、次のメソッドが用意されている。

GetMasterAutoDownload SetMasterAutoDownload | このパラメータは、セグメントを演奏するときに音色を自動的にダウンロードするかどうかを制御する。デフォルトではオフである。「バンドのダウンロードとアンロード」を参照すること。
GetMasterGrooveLevel SetMasterGrooveLevel | マスタ グルーブ レベルは、コマンド トラックで設定されるグルーブ レベルに常に加算される値である。返される値は 1 ～ 100 の範囲に収まるように必要に応じて調整される。
GetMasterTempo SetMasterTempo | マスタ テンポは、最終的な出力ツールによってテンポに適用されるスケーリング係数である。デフォルトの値は 1 である。0.5 でテンポは 2 分の 1 になり、2.0 で 2 倍のテンポになる。この値は、0.01 ～ 100.0 の範囲で設定できる。
GetMasterVolume SetMasterVolume | マスタ ボリュームは、増幅または減衰の係数で、1 デシベルの 100 分の 1 の単位で表される。そのパフォーマンス全体のデフォルトのボリュームと、同じシンセサイザを使用しているほかのすべてのパフォーマンスに適用される。設定できる値の範囲はポートによって決まる。ハードウェア MIDI ポートでは、マスタ ボリュームの変更はサポートされていない。


オーディオパスの使い方

DirectMusic パフォーマンスには 1 つ以上のオーディオパスが含まれる。オーディオパスは、さまざまなオブジェクトによってサウンド データの流れを管理する。オーディオパスには、パフォーマンス自体、セグメント、ツールグラフ、シンセサイザ、DirectSound バッファ、エフェクト DMO、および最終的なミキシングが行われるプライマリ DirectSound バッファが含まれる場合がある。

アプリケーションで 2D サウンド エフェクトや MIDI ファイルの再生以外の複雑な処理を行わない場合は、デフォルトの標準オーディオパスを設定し、そこですべての再生を行う。ただし、DirectX Audio の機能を最大限に利用するには、オーディオパスを制御する必要がある。

ここでは、オーディオパスの作成、オーディオパスでのセグメントの演奏、およびオーディオパス内のオブジェクトへのアクセスについて説明する。説明するトピックは、次のとおりである。

  • ポートからオーディオパスへの移行
  • オーディオパスの作成
  • デフォルトのオーディオパス
  • 標準オーディオパス
  • オーディオパスでのサウンドの再生
  • オーディオパスからのオブジェクトの取得


ポートからオーディオパスへの移行

DirectX 8.0 以前のバージョンの DirectMusic を使ってアプリケーションを作成していた場合、オーディオ出力へのルートの作成方法が変更されている。DirectX for Visual Basic では、パフォーマンスにポートを設定する必要がない。その代わり、オーディオパスにポートが組み込まれている。


オーディオパスの作成

アプリケーションでは、次の方法でオーディオパスを設定できる。

  • DirectMusicPerformance8.InitAudio を呼び出して、パフォーマンスのデフォルトの標準オーディオパスを作成する。「デフォルトのオーディオパス」を参照すること。
  • DirectMusicPerformance8.CreateStandardAudioPath を使って、1 つまたは複数のオーディオパスを作成する。「標準オーディオパス」を参照すること。
  • DirectMusic Producer で作成されたファイルからオーディオパス構成を取得し、構成オブジェクトを DirectMusicPerformance8.CreateAudioPath に渡す。
  • セグメントを演奏するときに、セグメントのオーディオパス構成から DirectMusic にオーディオパスを作成させる。この方法で作成されたオーディオパスは、一時的であり、アプリケーションでは認識されない。

セグメントに埋め込まれているオーディオパスの構成は、DirectMusicSegment8.GetAudioPathConfig を使って取得できる。オーディオパス構成オブジェクトは、固有のインターフェイスやメソッドを持たないので、アプリケーションで構成を変更することはできない。このオブジェクトに対して可能な処理は、IUnknown 型の変数として DirectMusicPerformance8.CreateAudioPath に渡すことだけである。サンプル コードについては、「オーディオパスでのサウンドの再生」を参照すること。

オーディオパス構成は、標準以外のオーディオパスを作成する唯一の方法である。たとえば、複数のパフォーマンス チャンネルが複数のバッファにルーティングされる場合、このマッピングはセグメントのオーディオパス構成で指定しなければならない。


デフォルトのオーディオパス

デフォルトのオーディオパスは、DirectMusicPerformance8.PlaySegmentEx の呼び出しでオーディオパスが指定されていない場合に使用される。

オーディオパスを作成してそれをデフォルトのオーディオパスにするには、DirectMusicPerformance8.InitAudio の lDefaultPathType パラメータで標準タイプを指定する。

既存のオーディオパスをデフォルトのオーディオパスにするには、それを DirectMusicPerformance8.SetDefaultAudioPath に渡す。デフォルトのオーディオパスを取得するには、DirectMusicPerformance8.GetDefaultAudioPath を使用する。


標準オーディオパス

オーディオパス構成オブジェクトから作成されたオーディオパス以外のオーディオパスで再生を行う場合は、1 つまたは複数の標準オーディオパスを作成する必要がある。

標準オーディオパスは、DirectMusicPerformance8.CreateStandardAudioPath の lType パラメータまたは DirectMusicPerformance8.InitAudio の lDefaultPathType パラメータで渡される値によって識別される。

DirectMusic によって定義されるオーディオパスは、標準バッファの組み合わせによってシンセサイザ出力のフローを管理する。標準バッファの一部には、エフェクト DMO が付加されている。次の表は、標準オーディオパスと、標準オーディオパスに含まれる標準的なバッファを示している。複数のオーディオパスで共有バッファを使用できる。

オーディオパスのタイプ | 標準バッファ | バッファを共有するか
DMUS_APATH_DYNAMIC_3D | 3D ドライ | いいえ
DMUS_APATH_DYNAMIC_MONO | モノラル | いいえ
DMUS_APATH_DYNAMIC_STEREO | ステレオ | いいえ
DMUS_APATH_SHARED_STEREOPLUSREVERB | ステレオ リバーブ | はい はい

標準的なバッファの特性を次の表に示す。「能力」の欄には、DirectSoundSecondaryBuffer8.GetCaps に渡される DSBCAPS 構造体の lFlags メンバで返される値が示されている。最後の欄は、バッファ オブジェクトから常に取得できるオブジェクトを示している。また、アプリケーションは DirectSoundSecondaryBuffer8.SetFX を使ってバッファにエフェクトを追加できる。この場合、ほかのオブジェクトも利用できる。取得した DirectSoundSecondaryBuffer8 オブジェクトは、どのバッファでも使用できる。オブジェクトの取得の詳細については、「オーディオパスからのオブジェクトの取得」を参照すること。

標準的なバッファ | 説明 | 能力 | オブジェクト
3D ドライ | モノラル 3D バッファ。 | DSBCAPS_CTRLFX DSBCAPS_CTRL3D DSBCAPS_CTRLFX DSBCAPS_CTRLVOLUME DSBCAPS_GLOBALFOCUS DSBCAPS_MUTE3DATMAXDISTANCE | DirectSound3DBuffer8
モノラル | エフェクトを持たないモノラル バッファ。 | DSBCAPS_CTRLFX DSBCAPS_CTRLPAN DSBCAPS_CTRLVOLUME DSBCAPS_GLOBALFOCUS | なし。
リバーブ | ミュージック リバーブ エフェクトを持つステレオ バッファ。 | DSBCAPS_CTRLFX DSBCAPS_CTRLPAN DSBCAPS_CTRLVOLUME DSBCAPS_GLOBALFOCUS | DirectSoundFXWavesReverb8
ステレオ | エフェクトを持たないステレオ バッファ。 | DSBCAPS_CTRLFX DSBCAPS_CTRLPAN DSBCAPS_CTRLVOLUME DSBCAPS_GLOBALFOCUS | なし。

標準オーディオパスの詳細については、次のトピックを参照すること。

  • DMUS_APATH_DYNAMIC_3D
  • DMUS_APATH_DYNAMIC_MONO
  • DMUS_APATH_DYNAMIC_STEREO
  • DMUS_APATH_SHARED_STEREOPLUSREVERB


DMUS_APATH_DYNAMIC_3D

3D ドライ タイプの非共有バッファを設定する。

アプリケーションは、lStage を DMUS_PATH_BUFFER に、lBuffer を 0 に設定して DirectMusicAudioPath8.GetObjectInPath を呼び出ことによって、3D ドライ バッファを表すオブジェクトを取得できる。


DMUS_APATH_DYNAMIC_MONO

3D パラメータまたは特殊効果を持たないモノラル タイプの非共有バッファを設定する。

アプリケーションは、lStage を DMUS_PATH_BUFFER に、lBuffer を 0 に設定して DirectMusicAudioPath8.GetObjectInPath を呼び出すことによって、バッファを表すオブジェクトを取得できる。


DMUS_APATH_DYNAMIC_STEREO

ステレオ タイプの非共有バッファを設定する。このオーディオパスは、ステレオ バッファ上のサウンド エフェクト用である。リバーブは使用できない。

アプリケーションは、lStage を DMUS_PATH_BUFFER に、lBuffer を 0 に設定して DirectMusicAudioPath8.GetObjectInPath を呼び出すことによって、バッファを表すオブジェクトを取得できる。


DMUS_APATH_SHARED_STEREOPLUSREVERB

リバーブおよびステレオ タイプのバッファを設定する。

ステレオ バッファは複数のオーディオパスで共有される。これはシンクイン バッファで、ほかのバッファからではなく、シンセサイザから直接データを受け取る。

アプリケーションは、lStage を DMUS_PATH_BUFFER に、lBuffer を 0 に設定して DirectMusicAudioPath8.GetObjectInPath を呼び出すことによって、ステレオ バッファを表すオブジェクトを取得できる。

リバーブ バッファも共有シンクイン バッファである。ステレオ バッファとは異なり、シンセサイザからのモノラル入力を受け取り、データをステレオ フォーマットに変換する。

アプリケーションは、dwStage を DMUS_PATH_BUFFER に、dwBuffer を 1 に設定して GetObjectInPath メソッドのいずれかを呼び出すことによって、リバーブ バッファを表すオブジェクトを取得できる。


オーディオパスでのサウンドの再生

アプリケーションで DirectMusicPerformance8.InitAudio を呼び出してデフォルトのオーディオパスを作成済みの場合は、DirectMusicPerformance8.PlaySegmentEx の AudioPath パラメータを省略して、デフォルトのパスでセグメントを再生できる。

デフォルトのオーディオパスがない場合、または、別のパスでセグメントを再生する場合は、次のいずれかの方法でオーディオパスを指定する。

  • AudioPath パラメータで DirectMusicAudioPath8 オブジェクトを指定する。通常は、オーディオパスの作成時に受信したオブジェクトを指定する。
  • lFlags に DMUS_SEGF_USE_AUDIOPATH を含める。このフラグを指定すると、セグメントによって、セグメント オブジェクトに埋め込まれた構成からオーディオパスが作成される。

注 DMUS_SEGF_USE_AUDIOPATH フラグを指定して作成されたオーディオパスは、セグメントの再生が停止すると直ちに解放される。オーディオパスにリバーブなどのエフェクトが含まれる場合、そのエフェクトは中断される。このような突然の中断を防ぐには、手動でオーディオパスを作成し、適切な時間をおいてから解放する。

DMUS_SEGF_USE_AUDIOPATH フラグを使って再生するセグメントについては、自動ダウンロードが有効になっていない限り、バンドはダウンロードされない。詳細については、「バンドの自動ダウンロード」を参照すること。

次のサンプル コードは、オーディオパス構成が埋め込まれている場合にそれを使ってセグメントを再生する。dmp は DirectMusicPerformance8 オブジェクトであり、dmSeg はサウンド ファイルの任意のタイプを表す DirectMusicSegment8 オブジェクトである。DirectMusicSegment8.GetAudioPathConfig の呼び出しでエラーが発生すると、path の値は Nothing のままになり、セグメントはデフォルトのオーディオパスで再生される。

Dim path As DirectMusicAudioPath8
Dim Config As IUnknown

If Not (dmSeg Is Nothing) Then

  On Error GoTo NOCONFIG
  Set path = Nothing
  Set Config = dmSeg.GetAudioPathConfig
  Set path = dmp.CreateAudioPath(Config, True)
NOCONFIG:
  On Error Resume Next
  dmp.PlaySegmentEx dmSeg, 0, 0, , path

End If

オーディオパス オブジェクトがある場合は、DirectMusicAudioPath8.SetVolume を使ってボリュームを変更できる。DirectMusicPerformance8.SetMasterVolume メソッドはそのシンセサイザで再生されるすべてのサウンドに影響するが、このメソッドは、そのオーディオパスで再生されるパフォーマンス チャンネルのボリュームだけを設定する。


オーディオパスからのオブジェクトの取得

オーディオパス内の特定のオブジェクトを取得しなければならない場合がある。このような場合の一般的な理由は次のとおりである。

  • DirectSound3DBuffer8 オブジェクトを取得することによってサウンドの 3D プロパティを操作するため。
  • プライマリ バッファから DirectSound3DListener8 オブジェクトを取得することによってグローバル 3D サウンド プロパティを設定するため。
  • DirectSoundSecondaryBuffer8 オブジェクトを取得することによってセカンダリ バッファのエフェクトを設定するため。
  • DirectSoundFXI3DL2Reverb8 などの DMO を取得することによってエフェクト パラメータを設定するため。

オーディオパスからオブジェクトを取得するには、DirectMusicAudioPath8.GetObjectInPath を呼び出す。次の表では、このメソッドのパラメータについて説明する。

lStage | guidObject | lPChannel を使用するか | lIndex を使用するか | iidInterface (標準)
DMUS_PATH_AUDIOPATH | DirectX for Visual Basic ではサポートしていない。アプリケーションは既に DirectMusicAudioPath8 オブジェクトを取得済みで、そこから GetObjectInPath を呼んでいる。
DMUS_PATH_AUDIOPATH_GRAPH | DirectX for Visual Basic ではサポートしていない。
DMUS_PATH_AUDIOPATH_TOOL | DirectX for Visual Basic ではサポートしていない。
DMUS_PATH_BUFFER | GUID_ALL | はい | いいえ。dwBuffer によって識別する | IID_DirectSoundSecondaryBuffer8
DMUS_PATH_BUFFER_DMO | GUID_DSFX_STANDARD_GARGLE などの DMO クラス ID、または 列挙する GUID_All | はい | いいえ。dwBuffer によって識別する | IID_DirectSoundGargle などの標準的な DMO の IID
DMUS_PATH_MIXIN_BUFFER | GUID_ALL | いいえ | はい | IID_DirectSoundSecondaryBuffer8
DMUS_PATH_MIXIN_BUFFER_DMO | DMO クラス GUID、または 列挙する GUID_All | いいえ | はい | IID_DirectSoundFXI3DL2Reverb などの標準的な DMO の IID
DMUS_PATH_PERFORMANCE | DirectX for Visual Basic ではサポートしていない。
DMUS_PATH_PERFORMANCE_GRAPH | DirectX for Visual Basic ではサポートしていない。
DMUS_PATH_PERFORMANCE_TOOL | DirectX for Visual Basic ではサポートしていない。
DMUS_PATH_PORT | DirectX for Visual Basic ではサポートしていない。
DMUS_PATH_PRIMARY_BUFFER | GUID_ALL | いいえ | いいえ | IID_DirectSound3DListener8
DMUS_PATH_SEGMENT (*) | GUID_ALL | いいえ | いいえ | IID_DirectMusicSegment8
DMUS_PATH_SEGMENT_GRAPH (*) | DirectX for Visual Basic ではサポートしていない。
DMUS_PATH_SEGMENT_TOOL (*) | DirectX for Visual Basic ではサポートしていない。
DMUS_PATH_SEGMENT_TRACK (*) | DirectX for Visual Basic ではサポートしていない。

標準的なバッファを取得するときの lIndex の値の詳細については、「標準オーディオパス」を参照すること。

既にエフェクト バッファへのオブジェクトがある場合は、DirectSoundSecondaryBuffer8.GetObjectInPath を使って DMO を取得することもできる。

オーディオパスのすべてのバッファについて DirectSoundSecondaryBuffer8 オブジェクトを取得できるが、一部のメソッドは有効ではない。詳細については、「DirectSoundSecondaryBuffer8」を参照すること。

オーディオパスから取得したバッファ オブジェクトに対して設定したグローバル変数は、DirectMusicPerformance8.CloseDown を呼び出す前に必ず Nothing に設定しなければならない。これを行わないと、CloseDown によってバッファが破棄され、プログラムの終了時に変数がスコープを超えてメモリ アクセス違反が発生する場合がある。


3D サウンド

DirectX Audio を使って、空間内のサウンドの位置を認識し、移動するサウンドにドップラー偏移を適用できる。

3D エフェクトは個々の DirectSound バッファに適用される。それぞれ独自のバッファを持つ複数のオーディオパスに異なるサウンドを指定できるので、異なるサウンドに容易に異なるパラメータを適用できる。

次のトピックでは、3D サウンドの基本的概念をいくつか紹介する。

  • 3D 空間の座標
  • 音源位置の認識

次のトピックでは、アプリケーション内での 3D サウンドの使い方についての情報を記述する。

  • DirectSound 3D バッファ
  • DirectSound 3D リスナー


3D 空間の座標

3D 空間での音源とリスナーの位置、速度、および向きは、デカルト座標の 3 本の座標軸、x 軸、y 軸、および z 軸の値で表される。これらの軸は、アプリケーションで確立された視点から相対的である。x 軸の値は左から右に、y 軸の値は下から上に、z 軸の値は手前から奥に行くほど大きくなる。

D3DVECTOR 型は、3 つの軸で位置、速度、または向きを記述する値を格納する。

慣習的に、ベクトルはかっこで囲まれ、カンマで区切られた (x, y, z) の順序の 3 つの値で表される。

位置の場合、これらの値はデフォルトでメートル単位である。アプリケーションが 3D グラフィックの測定単位としてメートル以外のものを使っている場合、距離係数を設定し、アプリケーションの使う距離単位が何メートルに相当するかを浮動小数点の値として表現する。たとえば、アプリケーションがフィート単位を使っている場合、距離係数として 0.3048 を指定するが、これは 1 フィートをメートル単位で表現したものである。詳細については、「距離係数」を参照すること。

速度の場合、ベクトルは、各軸に沿った移動速度を 1 秒あたりの単位で表す。この場合も、デフォルトの単位はメートルであるが、アプリケーションで変更できる。

向きの場合、値は任意の単位であり、互いに相対的である。3D 空間のベース ビューが北向きで、地面のレベルで、リスナーの向きが (1, 0, 0)、つまり、x 軸が正で、ほかの 2 つの軸が変わらない場合、リスナーは真東を向く。このベクトルが (1, 0, 1) の場合、リスナーの向きは北東になる。(-1, 0, 1) の場合、リスナーは北西を向く。ベクトルの値は絶対的な単位ではないので、最後の例は (-5, 0, 5) または (-0.25, 0, 0.25) と表すこともできる。

2D 空間でのベクトルのしくみは、グラフ用紙に描いてみるとわかりやすい。値が用紙の下から上、左から右に向かって大きくなるようにする。(0, 0) から (1, 1) に向かって描いた直線は、(0, 0) から (5, 5) に向かって描いた直線と、向き、つまり方向が同じである。ただし、2 番目の直線は距離、つまり速度が大きいことを示す。3D ベクトルの場合も、軸が増えるだけで、これと同様である。


音源位置の認識

現実の世界では、空間内の音源位置の認識は、複数の要素に影響される。これらの要素のすべてが音響的ではない。最も重要なものの 1 つに視覚がある。サウンド自体の手がかりには、次のようなものがある。

  • 全体的な音量。音源がリスナーから遠ざかると、認識される音量は一定速度で減少する。この現象はロールオフと呼ばれている。
  • 聴感上の強度の違い。リスナーの右方向で発生した音は、左耳より右耳の方で大きく聞こえる。
  • 到達のずれ。リスナーの右方向で発生した音は、左耳より少しだけ早く右耳に到達する。このずれの時間は、約 1 ミリ秒である。
  • 消音。耳が前向きについていることと、その形状のために、リスナーの後ろ方向で発生した音は、前で発生した音に比べてかすかに弱くなっている。さらに、右方向で音が発生した場合、左耳に届く音は、頭部に遮られることと左耳の向きによって弱まる。

人間が音の位置を識別するための手がかりはこれだけではないが、ここに挙げたのは主要なものである。そして DirectX Audio の位置決めシステムはこれらの要素を提供する。3D サウンド用に最適化されたハードウェアは、異なる方向から発せられる音の高さやタイミングに対する耳たぶのエフェクトなど、ほかの手がかりもサポートできる。このエフェクトの背景にある数学的理論を頭部伝達関数 (HRTF) と呼ぶ。

ほとんどの場合、DirectSound は 2 つのスピーカまたはヘッドフォンで仮想 3D エフェクトを作成する。ただし、ユーザーがコントロール パネルでサラウンド サウンド スピーカ構成を選択した場合は、WDM ドライバを使用する 4 チャンネル システムを利用することもできる。詳細については、「DSBUFFERDESC」を参照すること。


DirectSound 3D バッファ

3D 環境での各音源は DirectSound3DBuffer8 オブジェクトによって表される。このオブジェクトは、このオブジェクトを取得したバッファの 3D プロパティを制御する。このオブジェクトは、DSBCAPS_CTRL3D フラグを指定して作成されたセカンダリ サウンド バッファからのみ取得できる。このオブジェクトのメソッドを使用して、単一の音源のパラメータを設定および取得する。

DirectSound の 3D 能力を利用するときは、アプリケーションはモノラル音源を提供すべきである。DSBCAPS_CTRL3D フラグを指定してバッファを作成する場合、ウェーブ フォーマットに複数のチャンネルが含まれていると、エラーになる。

ここでは、アプリケーションが 3D バッファ オブジェクトを取得および管理する方法について説明する。以下のトピックについて説明する。

  • 3D バッファ オブジェクトの取得
  • 3D バッファのバッチ パラメータ
  • 最小距離と最大距離
  • 処理モード
  • バッファの位置座標と速度
  • サウンド コーン


3D バッファ オブジェクトの取得

DirectSound3DBuffer8 オブジェクトは、DSBUFFERDESC 型の lFlags メンバで DSBCAPS_CTRL3D フラグを指定して作成されたDirectSound セカンダリ バッファから取得される。

アプリケーションが DirectMusic のパフォーマンスおよびオーディオパスを使用している場合、DMUS_APATH_DYNAMIC_3D を lType パラメータとして DirectMusicPerformance8.CreateStandardAudioPath に渡すことによって、3D バッファを含むオーディオパスを作成できる。

構成オブジェクトから適切なオーディオパスを作成することもできる。オーディオパス構成によって、バッファの 3D パラメータを指定できる。オーディオパスを作成するときに、バッファの 3D プロパティはこれらのパラメータを使って初期化される。

オーディオパス内の 3D バッファを表すオブジェクトを取得するには、次の例のように、lStage を DMUS_PATH_BUFFER に設定して、DirectMusicAudioPath8.GetObjectInPath を呼び出す。

Dim dsb As DirectSound3dBuffer8

Set dsb = dmAudioPath.GetObjectinPath(DMUS_PCHANNEL_ALL, _
    DMUS_PATH_BUFFER, 0, GUID_ALL, 0, IID_DirectSound3DBuffer)

次の例は、DirectMusic パフォーマンスを使用しないアプリケーションで DirectSound3DBuffer8 オブジェクトを作成する方法を示している。ここで、m_ds は DirectSound8 オブジェクトである。

Dim dsbd As DSBUFFERDESC
Dim dsBuffer As DirectSoundSecondaryBuffer8
Dim ds3dBuffer As DirectSound3DBuffer8

' セカンダリ バッファを作成する。

dsbd.lFlags = DSBCAPS_CTRL3D
Set dsBuffer = m_ds.CreateSoundBufferFromFile("sound.wav", dsbd)

' 3D バッファ オブジェクトを取得する。

Set ds3dBuffer = dsBuffer.GetDirectSound3DBuffer


3D バッファのバッチ パラメータ

アプリケーションは、3D サウンド パラメータの取得や設定を個別またはバッチ単位で実施できる。個別の値を設定するには、アプリケーションで適用可能な DirectSound3DBuffer8 メソッドを使用できる。しかし、すべての値を一度に設定または取得する必要が生じることもよくある。その場合は、DirectSound3DBuffer8.GetAllParameters と DirectSound3DBuffer8.SetAllParameters の各メソッドを使う。

また、パラメータの変更は、それらに遅延のフラグを付けておき、その後すべてを一度に実行することでより効率的に行うことができる。詳細については、「遅延設定」を参照すること。


最小距離と最大距離

リスナーが音源に近づくにつれてサウンドが大きくなり、距離が半分になったときに音のボリュームは倍増する。しかし、特定の点を過ぎると、ボリュームが増加し続けるのは合理的ではない。これが音源の最小距離である。

アプリケーションが異なる音の絶対ボリューム レベルの差を補正しなければならない場合、最小距離は特に役立つ。たとえば、ジェット エンジンの音は蜂の羽音よりもずっと大きいが、実用上の理由でこれらの音を同程度の絶対ボリュームで録音しなければならない。アプリケーションはジェット エンジンの最小距離を 100 メートル、蜂の最小距離を 2 センチに設定することが考えられる。これらの設定では、リスナーが 200 メートル離れるとジェット エンジンは半分のボリュームになり、リスナーが 4 センチ離れると蜂の羽音は半分のボリュームになる。

サウンド バッファのデフォルトの最小距離 DS3D_DEFAULTMINDISTANCE は、1 単位、つまりデフォルトの距離係数では 1 メートルと定義されている。この値を変更しない限り、リスナーから 1 メートル離れた位置で音は最大になり、2 メートル離れると半分の大きさ、4 メートル離れると 1/4 の大きさになる。ほとんどのサウンドでは、最小距離をこれよりも大きく設定し、距離が大きくなってもサウンドが急速に消えないようにする。

音源の最大距離とは、それ以上離れても音がより小さくならない距離を意味する。DirectSound の 3D バッファのデフォルトの最大距離 (DS3D_DEFAULTMAXDISTANCE) は 10 億であり、音が聞こえなくなった後も引き続き減衰を計算しなければならないことを意味する。不必要な処理を避けるために、アプリケーションは適切な最大距離を設定し、バッファを作成する際に DSBCAPS_MUTE3DATMAXDISTANCE フラグを含めるべきである。このフラグは、オーディオパスの一部として作成された標準的な 3D バッファについては自動的に設定される。「標準オーディオパス」を参照すること。

サウンドが聞こえなくなることを防止する目的でも、最大距離を利用できる。たとえば、あるサウンドの最小距離を 100 メートルに設定し、1,000 メートル以上離れるとそのサウンドが事実上聞こえなくなると仮定する。ここで最大距離を 800 メートルに設定すると、距離にかかわりなく、そのサウンドは最大ボリュームの少なくとも 1/8 で聞こえることが保証される。もちろん、この場合は DSBCAPS_MUTE3DATMAXDISTANCE フラグを設定しない。

次の図は、距離が大きくなるにつれて、最小距離と最大距離がジェット エンジンの音と蜂の羽音の大きさにどのように影響するかを示している。

アプリケーションで最小距離値を設定および取得するには、DirectSound3DBuffer8.SetMinDistance と DirectSound3DBuffer8.GetMinDistance の各メソッドを使う。同様に、最大距離値を設定および取得するには DirectSound3DBuffer8.SetMaxDistance と DirectSound3DBuffer8.GetMaxDistance の各メソッドを使う。

デフォルトでは、距離値はメートル単位で表される。「距離係数」を参照すること。

すべてのサウンド バッファで、距離がボリュームに及ぼすエフェクトを調整するには、ロールオフ係数を変更する。


処理モード

サウンド バッファには 3 つの処理モードがある。標準、頭相対 (リスナー相対)、および無効の各モードである。

標準モードでは、音源はワールド空間内の絶対位置と絶対方向に基づいて処理される。これはデフォルトのモードである。

頭相対 (リスナー相対) モードでは、リスナーの移動と回転に応じて、バッファはワールド空間内で自動的に位置調整される。DirectSound3DBuffer8.SetPosition、DirectSound3DBuffer8.SetVelocity、DirectSound3DBuffer8.GetConeOrientation などのメソッドで値の設定と取得が行えるが、これらはいずれもリスナーの現在の位置、速度、向きに対する相対的なものである。

無効モードでは 3D サウンド処理は無効になり、サウンドはリスナーの頭の中心で発生しているように聞こえる。

アプリケーションは DirectSound3DBuffer8.SetMode メソッドを使って 3D サウンド バッファのモードを設定する。


バッファの位置座標と速度

3D サウンドには位置と速度がある。これらの値の指定は、すべてアプリケーションで行う。

位置は処理モードに基づき、ワールド空間かリスナーのどちらかを基準とした相対的なベクトルとして表される。

速度は秒あたりの距離単位で測定される。デフォルトではメートル/秒である。速度はドップラー偏移のエフェクトを計算するためにのみ使用され、音源の実際の移動側に対応している必要はない。

アプリケーションは、DirectSound3DBuffer8.SetPosition と DirectSound3DBuffer8.GetPosition の各メソッドを使って、3D 空間での音源の位置を設定および取得できる。

速度を設定または取得するには、DirectSound3DBuffer8.SetVelocity と DirectSound3DBuffer8.GetVelocity の各メソッドを使用する。速度は秒あたりの距離単位で測定される。デフォルトではメートル/秒である。


サウンド コーン

向きを持たないサウンドは、どの向きでも、距離に応じて大きさが決まる。向きのあるサウンドは、その向きに向かったときに最も大きくなる。方向のあるサウンドの大きさを表すモデルを、サウンド コーンと呼ぶ。サウンド コーンは、内部コーンと外部コーンで形成される。

内部コーン内の角度では、サウンドのボリュームは、バッファの基本的なボリューム、リスナーからの距離、リスナーの向きなどを考慮しても、コーンがない場合と同じになる。

外部コーンの外側の角度では、アプリケーションによって設定された係数によって通常のボリュームが減衰される。外部コーンのボリュームは、1/100 dB 単位の負の数で表される。デフォルトのボリュームを 0 とし、このボリュームはそこからの減衰を表すからである。

内部コーンと外部コーンの間の角度は、内部ボリュームから外部ボリュームへのトランジションである。角度が増加するにつれて、ボリュームは小さくなる。

次の図は、サウンド コーンの概念を示している。

すべての 3D サウンド バッファはサウンド コーンである。しかし、外部ボリュームは減衰せず、内部コーンと外部コーンの角度はどちらも 360 度なので、デフォルトではバッファは全方向の音源として動作する。アプリケーションがこれらの値を変更しない限り、サウンドには見かけの向きはない。

サウンド コーンを適切に設計すると、アプリケーションに劇的なエフェクトが追加される。たとえば音源を部屋の中央に置き、音源の方向を、廊下に面して開いたドアの向きに設定する。次にそのドアの幅に合わせて内部コーンの角度を設定する。外部コーンをそれより少しだけ広く設定し、外部コーンのボリュームを聴取不可能に設定する。リスナーが廊下を歩き、ドアの近くまで来るとサウンドが聞こえ始める。そして開いているドアの正面に来るとサウンドは最大になる。

アプリケーションは、DirectSound3DBuffer8.SetConeAngles と DirectSound3DBuffer8.GetConeAngles の各メソッドを使って、サウンド コーンを定義する角度を設定および取得する。外部コーンの角度は、常に内部コーンの角度以上でなければならない。

アプリケーションは、DirectSound3DBuffer8.SetConeOrientation と DirectSound3DBuffer8.GetConeOrientation の各メソッドを使って、サウンド コーンの向きを設定および取得する。

アプリケーションは、DirectSound3DBuffer8.SetConeOutsideVolume と DirectSound3DBuffer8.GetConeOutsideVolume の各メソッドを使って、外部コーンのボリュームを設定および取得する。


DirectSound 3D リスナー

仮想 3D 環境では、実世界と同様に、サウンドは受信ポイントとの関係でのみ存在する。DirectX Audio アプリケーションの 3D サウンド エフェクトは、サウンド バッファの位置と向きと速度だけではなく、仮想リスナーの位置と向きと速度の影響を受ける。

デフォルトでは、リスナーはすべてのベクトルが 0 の位置に静止し、Z 軸の正の方向を向き、頭を Y 軸の正の方向にしている。リスナーを表すオブジェクトを取得することによって、アプリケーションはこれらのすべての値を変更して仮想空間でのユーザーの動きと向きを反映できる。リスナー オブジェクトは、ドップラー効果の量や距離に応じたボリュームの減衰など、聴感環境の一般的なパラメータもコントロールする。

ここでは、アプリケーションがリスナーを取得し、グローバル 3D サウンド パラメータを管理する方法について説明する。説明するトピックは、次のとおりである。

  • 3D リスナーの取得
  • 3D リスナーのバッチ パラメータ
  • 遅延設定
  • 距離係数
  • リスナーの向き
  • リスナーの位置座標と速度
  • ドップラー係数
  • ロールオフ係数


3D リスナーの取得

グローバル サウンド パラメータは、DirectSound3DListener8 オブジェクトを使って設定および取得される。このオブジェクトは、プライマリ サウンド バッファから取得される。アプリケーションのプライマリ バッファは 1 つだけで、リスナーも 1 人だけである。

DirectMusic のパフォーマンスとオーディオパスを使って 3D サウンドを再生する場合は、DirectMusicAudioPath8.GetObjectInPath を使い、lStage パラメータを DMUS_PATH_PRIMARY_BUFFER に設定して、オーディオパスからリスナーを取得できる。次の例では、AudioPath は DirectMusicAudioPath8 オブジェクトである。

Dim dx As New DirectX8

Dim perf As DirectMusicPerformance8
Dim audparams As DMUS_AUDIOPARAMS
Dim audiopath As DirectMusicAudioPath8
Dim listener As DirectSound3dListener8

Private Sub Form_Load()
  Set perf = dx.DirectMusicPerformanceCreate
  perf.InitAudio Me.hWnd, DMUS_AUDIOF_ALL, audparams, _
      Nothing, Nothing, DMUS_APATH_DYNAMIC_3D, 16
  Set audiopath = perf.GetDefaultAudioPath
  Set listener = audiopath.GetObjectinPath(DMUS_PCHANNEL_ALL, _
      DMUS_PATH_PRIMARY_BUFFER, 0, vbNullString, 0, _
      IID_DirectSound3DListener)
End Sub

アプリケーションが、DirectSound API を使って、独自のサウンド バッファを作成および管理する場合は、プライマリ バッファ オブジェクトを作成し、このオブジェクトからリスナー インターフェイスを取得する必要がある。

プライマリ バッファ オブジェクトを作成するには、DirectSound8.CreatePrimarySoundBuffer メソッドを使い、関連する DSBUFFERDESC 型の lFlags メンバで DSBCAPS_CTRL3D と DSBCAPS_PRIMARYBUFFER の各フラグを指定する。そして作成されたバッファに対して DirectSoundPrimaryBuffer8.GetDirectSound3DListener メソッドを呼び出し、DirectSound3DListener8 オブジェクトを取得する。次の例でこのステップを示す。ds はグローバルな DirectSound8 オブジェクトである。

Dim dsbd As DSBUFFERDESC
Dim dsbPrimary As DirectSoundPrimaryBuffer8
Dim waveFormat As WAVEFORMATEX
Dim ds3dListener As DirectSound3DListener8

' プライマリ バッファを作成する。プライマリ バッファについては waveFormat パラメータは無視されるので、
' 初期化する必要はない。

dsbd.lFlags = DSBCAPS_CTRL3D Or DSBCAPS_PRIMARYBUFFER
Set dsbPrimary = ds.CreatePrimarySoundBuffer(dsbd, waveFormat)

' DirectSound3DListener8 オブジェクトを作成する。

Set ds3DListener = dsbPrimary.GetDirectSound3DListener

リスナーを取得した後は、プライマリ バッファ オブジェクトは必要なくなり、スコープ外に出せる。


3D リスナーのバッチ パラメータ

アプリケーションは、3D リスナー オブジェクト パラメータの取得や設定を個別またはバッチ単位で実施できる。個別の値を設定するには、アプリケーションで適用可能な DirectSound3DListener8 オブジェクト メソッドを使用できる。しかし、リスナーを表現するすべての値を一度に設定または取得する必要が生じることもよくある。その場合は、DirectSound3DListener8.GetAllParameters と DirectSound3DListener8.SetAllParameters の各メソッドを使うと、バッチ パラメータ操作を 1 回の呼び出しで実行できる。

また、パラメータの変更は、それらに遅延のフラグを付けておき、その後すべてを一度に実行することでより効率的に行うことができる。詳細については、「遅延設定」を参照すること。


遅延設定

3D サウンド バッファとリスナーの設定を変更するたびに、再ミキシングが行われ、CPU サイクルを消費する。3D 設定の変更による処理性能への影響を最小限に抑えるには、3D 設定を変更する DirectSound3DListener8 と DirectSound3DBuffer8 のいずれかのメソッドの applyFlag パラメータで DS3D_DEFERRED フラグを指定する。その後 DirectSound3DListener8.CommitDeferredSettings メソッドを呼び出し、遅延されていたすべてのコマンドを 1 回で実行する。

注 遅延設定は即時設定によってオーバーライドされる。たとえば、DS3D_DEFERRED フラグを指定してリスナー速度を (1.0, 0.0, 0.0) に設定した後、DS3D_IMMEDIATE フラグを指定してリスナー速度を (2.0, 0.0, 0.0) に設定すると、速度は (2.0, 0.0, 0.0) になり、CommitDeferredSettings を呼び出しても変更されない。


距離係数

距離係数は、ベクトルの単位となるメートル数である。デフォルトの距離係数は 1.0 である。バッファの速度が (2.0, 0.0, 0.0) である場合、音源は X 軸に沿って、2 メートル/秒で移動すると見なされる。アプリケーションが 3D グラフィック ベクトルの測定単位としてメートル以外の単位を使っている場合は、その単位に応じて距離係数も変更できる。

たとえば、現在のアプリケーションが測定の基本単位としてフィート (0.3408 メートル) を使っているとする。この場合は、DirectSound3DListener8.SetDistanceFactor メソッドを呼び出して、distanceFactor パラメータとして 0.3048 を指定する。それ以降、メソッドを呼び出す際にパラメータをフィート単位で指定すると、それらの値はメートル単位に自動的に換算される。

DirectSound3DListener8.GetDistanceFactor メソッドを使うと、リスナーに対して設定されている現在の距離係数を取得できる。

距離係数は、1 秒あたり n 単位で表される実際の速度を変更することにより、主にドップラー効果に影響を及ぼす。ロールオフに直接的な影響を及ぼすことはない。距離に応じた減衰率は、この単位を使った最小距離に基づいているからである。あるサウンドの最小距離を 2 単位に設定した場合、4 単位離れるとボリュームは半分になる。距離がフィートやメートルやほかの単位であっても、これは共通である。詳細については、「最小距離と最大距離」を参照すること。


リスナーの向き

リスナーの向きは、リスナーの頭の中心を原点とする 2 つのベクトル、上方ベクトルと前方ベクトルの関係によって定義される。上方ベクトルは頭頂部を通る上向きの直線で、前方ベクトルは上方ベクトルと直角をなしてリスナーの顔を通る直線である。次の図はこれらの関係を示している。

アプリケーションは DirectSound3DListener8.SetOrientation と DirectSound3DListener8.GetOrientation の各メソッドを使って、リスナーの向きを設定および取得できる。

デフォルトでは、前方ベクトルが (0.0, 0.0, 1.0)、上方ベクトルが (0.0, 1.0, 0.0) である。これら 2 つのベクトルは、常に互いに対して直角でなければならない。必要に応じて、DirectSound は前方ベクトルに調整を加え、上方ベクトルに対して直角の関係を保つ。


リスナーの位置座標と速度

アプリケーションは DirectSound3DListener8.SetPosition と DirectSound3DListener8.GetPosition の各メソッドを使って、3D 空間におけるリスナーの位置を設定および取得できる。

DirectSound が移動するリスナーに対するドップラー効果を計算する際に使う速度値を設定または取得するには、DirectSound3DListener8.SetVelocity と DirectSound3DListener8.GetVelocity の各メソッドを使う。速度は秒あたりの距離単位で測定される。デフォルトではメートル/秒である。

バッファと同様、リスナーの位置と速度とは完全に独立している。リスナーの適切な速度を設定する作業は、アプリケーションに依存している。


ドップラー係数

DirectSound は、速度を持つバッファやリスナーに対して、自動的にドップラー効果を作成する。このエフェクトは累積する。リスナーとサウンド バッファの両方が移動している場合、システムは相対速度を自動的に計算し、それに従ってドップラー効果を調整する。

現実的なドップラー効果をアプリケーションに追加するには、移動しているあらゆるオブジェクトの速度を計算し、その音源またはリスナーの適切な速度を設定しなければならない。特定の状況では特殊効果をもたらすために、この値を自由に拡張または減少させてよい。ドップラー係数を変更すると、ドップラー偏移を全体的に増加または減少させられる。

ドップラー係数は、DS3D_MINDOPPLERFACTOR から DS3D_MAXDOPPLERFACTOR の範囲で変更できるが、これらはそれぞれ 0.0 と 10.0 に設定されている。値 0 は、サウンドにドップラー偏移を適用しないことを意味する。ほかの値は、実世界のドップラー偏移に対する乗数を表す。言い換えれば、値 1 (または DS3D_DEFAULTDOPPLERFACTOR) は実世界で体験するドップラー偏移をサウンドに適用すること、値 2 は実世界のドップラー偏移の 2 倍を意味する。以下同様である。

DirectSound3DListener8.SetDopplerFactor と DirectSound3DListener8.GetDopplerFactor の各メソッドを使うと、ドップラー係数を設定および取得できる。


ロールオフ係数

ロールオフとは、リスナーとサウンドの距離によって生じる音の減衰の度合である。DirectSound はロールオフ係数と呼ぶ変数により、ロールオフの無視、誇張、実世界と同じエフェクトの再現ができる。

ロールオフ係数は、DS3D_MINROLLOFFFACTOR から DS3D_MAXROLLOFFFACTOR の範囲で変更できるが、これらはそれぞれ 0.0 と 10.0 に設定されている。値 DS3D_MINROLLOFFFACTOR は、サウンドにロールオフを適用しないことを意味する。ほかの値は、実世界のロールオフに対する乗数を表す。言い換えれば、値 1 (DS3D_DEFAULTROLLOFFFACTOR) は実世界で体験するロールオフをサウンドに適用すること、値 2 は実世界のロールオフの 2 倍を意味する。以下同様である。

DirectSound3DListener8.SetRolloffFactor と DirectSound3DListener8.GetRolloffFactor の各メソッドを使うと、ロールオフ係数を設定および取得できる。

個別のサウンド バッファの距離によるエフェクトを変更するために、そのバッファの最小距離を設定できる。詳細については、「最小距離と最大距離」を参照すること。


エフェクトの使い方

DirectX Audio は、DMO (DirectX Media Object) によるサウンドのエフェクト処理をサポートしている。DMO の概要については、DirectShow のマニュアルの「DirectX Media Object の概要」を参照すること。

すべての DirectX アプリケーションで、標準エフェクトのセットを使用できる。その他の DMO はシステムに登録される。

ウェーブ リバーブ以外のすべての標準的な DMO は、DirectSound がサポートしている任意のサンプル レートで、1 つまたは 2 つのチャンネルを使用して、8 ビットまたは 16 ビットの PCM ウェーブ フォーマットのデータを処理できる。ウェーブ リバーブは 8 ビットのサンプルをサポートしていない。

次のトピックでは、エフェクトの設定と使い方について説明する。

  • バッファでのエフェクトの設定
  • エフェクト パラメータ
  • 標準エフェクト

ここでは、オーディオパスにおけるエフェクトの使い方を中心に説明するが、多くの情報は、独自の DirectSound バッファを管理するアプリケーションにも対応する。「DirectSound でのエフェクトの使い方」を参照すること。


バッファでのエフェクトの設定

DirectMusic Producer で作成したセグメントを、オーディオパス構成を使って演奏している場合、エフェクトは構成オブジェクトからオーディオパスを作成したときに設定される。標準オーディオパスにはエフェクトも保持される。ただし、実行時にカスタム オーディオパスでエフェクトを実装したり、標準オーディオパスにエフェクトを追加したい場合がある。たとえば、ウェーブまたは MIDI ファイルにエフェクトを適用できるように、標準オーディオパスにエフェクトを追加したい場合がある。

オーディオパスにエフェクトを適用するには、まずパス上のバッファへの DirectSoundSecondaryBuffer8 オブジェクトを取得する。次に、DirectSoundSecondaryBuffer8.SetFX を使って、そのバッファに 1 つまたは複数のエフェクトを設定する。オーディオパスは非アクティブでなければならない。

バッファ オブジェクトを取得する方法については、「オーディオパスからのオブジェクトの取得」を参照すること。GetObjectInPath の呼び出しで標準オーディオパス バッファを識別する方法については、「標準オーディオパス」のオーディオパスのタイプを参照すること。

次のサンプルコードでは、標準オーディオパスを設定し、パスからバッファを取得し、バッファ上でエコー エフェクトを設定している。dmPerformance は DirectMusicPerformance8 オブジェクトである。

Dim dmAudioPath As DirectMusicAudioPath8
Dim dsBuffer As DirectSoundSecondaryBuffer8
Dim DSEffects(0) As DSEFFECTDESC
Dim lResults(0) As Long

' 音源および環境リバーブ バッファを使って、
' 標準オーディオパスを作成する。パスはアクティブにしない。
' バッファが実行中の場合、SetFX は失敗する。

Set dmAudioPath = dmPerformance.CreateStandardAudioPath( _
    DMUS_APATH_DYNAMIC_3D, 128, False)

' オーディオパスのバッファを取得する。

Set dsBuffer = dmAudioPath.GetObjectinPath(DMUS_PCHANNEL_ALL, _
    DMUS_PATH_BUFFER, 0, GUID_ALL, 0, IID_DirectSoundSecondaryBuffer)

' エフェクトを記述する。

DSEffects(0).lFlags = 0
DSEffects(0).guidDSFXClass = DSFX_STANDARD_ECHO

' バッファのエフェクトを設定する。

dsBuffer.SetFX 1, DSEffects, lResults

' ここで lResults(0) の値をチェックし、エフェクトが
' どのように割り当てられているかを確認できる。

dmAudioPath.Activate (True)


エフェクト パラメータ

サウンド エフェクトのパラメータを設定または取得するには、まず、そのエフェクトを含むバッファから適切なオブジェクトを取得する必要がある。次のクラスを使って、DirectX Audio で提供される DMO のパラメータにアクセスできる。

  • DirectSoundFXChorus8
  • DirectSoundFXCompressor8
  • DirectSoundFXDistortion8
  • DirectSoundFXEcho8
  • DirectSoundFXFlanger8
  • DirectSoundFXGargle8
  • DirectSoundFXI3DL2Reverb8
  • DirectSoundFXParamEq8
  • DirectSoundFXWavesReverb8

エフェクト オブジェクトを取得するには、lStage として DMUS_PATH_BUFFER_DMO を DirectMusicAudioPath8.GetObjectInPath に渡す。オーディオパスに複数のバッファが含まれる場合、lBuffer はバッファのインデックスでなければならない。標準オーディオパスのバッファのインデックス番号については、「標準オーディオパス」のオーディオパスのタイプを参照すること。

次のサンプル コードは、バッファのガーグル エフェクトのインターフェイスを取得する。次に、このインターフェイスを使って、エフェクトのパラメータを変更している。dmAudioPath は、オーディオパス構成オブジェクトで DirectMusicPerformance8.CreateAudioPath を呼び出すことによって取得された DirectMusicAudioPath8 オブジェクトであるとする。

Dim gargleParams As DSFXI3DL2GARGLE
Dim gargleFX As DirectSoundFXGargle8

Set gargleFX = dmAudioPath.GetObjectinPath(DMUS_PCHANNEL_ALL, _
    DMUS_PATH_BUFFER_DMO, 0, DSFX_STANDARD_GARGLE, 0, _
    IID_DirectSoundFXGARGLE)

gargleParams = gargleFX.GetAllParameters
gargleParams.lRateHZ = DSFXGARGLE_RATEHZ_MIN
gargleFX.SetAllParameters gargleParams

アプリケーションが独自の DirectSound バッファを管理する場合、エフェクト パラメータの変更をすぐに実行する必要がある。効率を高めるため、DirectSoundSecondaryBuffer8.Play を呼び出す前に、DirectSound は再生カーソルの位置から開始して 100 ミリ秒のサウンド データを処理する。この処理は、以下のいずれかの呼び出しが実行された後に行うことができる。

  • DirectSound8.CreateSoundBufferFromFile
  • DirectSoundSecondaryBuffer8.WriteBuffer
  • DirectSoundSecondaryBuffer8.Stop
  • DirectSoundSecondaryBuffer8.SetCurrentPosition
  • DirectSoundSecondaryBuffer8.SetFX

これらのメソッドのいずれかを呼び出した後でエフェクト パラメータを変更した場合、処理済みのデータが再生されるまで、新しいパラメータは聞こえない。これを回避するには、以下のいずれかを実行する。

  • バッファへのデータの書き込みを、パラメータの変更前ではなく変更後に行う。このテクニックは、既にデータを格納している、ファイルから作成されたバッファには適用されない。
  • バッファで Stop または SetCurrentPosition を呼び出し、データの処理を強制的にパラメータ設定後にする。


標準エフェクト

ここでは、DirectX Audio のサウンド エフェクトを紹介する。次のエフェクトについて説明する。

  • コーラス
  • コンプレッション
  • ディストーション
  • エコー
  • 環境リバーブ
  • フランジ
  • ガーグル
  • パラメトリック イコライザ
  • ウェーブ リバーブ


コーラス

コーラスは、元のサウンドに若干の遅延を付加してエコーをかけ、エコーの遅延を若干変調して作成される音声二重化エフェクトである。

このエフェクトは、DirectSoundFXChorus8 オブジェクトによって表される。そのパラメータは、DSFXCHORUS 型に格納される。


コンプレッション

コンプレッションとは、特定の振幅を超えるシグナルの変動を削減することである。

このエフェクトは、DirectSoundFXCompressor8 オブジェクトによって表される。そのパラメータは、DSFXCOMPRESSOR 型に格納される。


ディストーション

ディストーションを実行するには、信号に和音を追加する。これによって、レベルが上がったときにウェーブフォームの最上部が四角形になるか、切り取られる。

このエフェクトは、DirectSoundFXDistortion8 オブジェクトによって表される。そのパラメータは、DSFXDISTORTION 型に格納される。


エコー

エコー エフェクトによって、サウンド全体が固定遅延の後、繰り返される。

このエフェクトは、DirectSoundFXEcho8 オブジェクトによって表される。そのパラメータは、DSFXECHO 型に格納される。


環境リバーブ

DirectX では、Interactive Audio Special Interest Group によって発行された Interactive 3-D Audio, Level 2 (I3DL2) 仕様に基づく環境リバーブをサポートしている。

DirectX 環境リバーブ エフェクトは、I3DL2 仕様のリスナー プロパティの実装である。このリリースでは、音源プロパティはサポートされていない。

リスナーに届くサウンドは、3 つの一時的なコンポーネントを持つ。

  • 直接パスは、どのサーフェスにも反射せず、音源からリスナーにまっすぐに進むオーディオ シグナルである。したがって、直接パス シグナルは 1 つしかない。
  • 初期反射音は、壁、床、天井などのサーフェスに 1、2 回反射した後、リスナーに届くオーディオ シグナルである。シグナルが、リスナーに届くまでに 1 回だけ壁に当たった音である場合、このシグナルは 1 次反射音と呼ばれる。リスナーに届くまでに壁に 2 回反射した音は、2 次反射音と呼ばれる。人間が通常個別に感知できるのは、1 次反射音または 2 次反射音だけである。
  • 後期リバーブ、または単なるリバーブは、低次反射音の組み合わせ、通常、強さが減少していく連続するエコーの重なりで構成される。

初期反射音と後期リバーブの組み合わせは、室内エフェクトと呼ばれることもある。

リバーブ プロパティには次のものがある。

  • 初期反射音および後期リバーブの減衰。
  • ロールオフ係数、つまり反射したシグナルが距離に応じて減衰する割合。直接パスのロールオフ係数は、DirectSound リスナーによって管理される。
  • 反射音の遅延。これは、直接パスのシグナルの到達と、最初の初期反射音の到達との時間差である。
  • リバーブの遅延。これは、最初の初期反射音と、後期リバーブの到達との時間差である。
  • ディケイ時間。これは、後期リバーブの到達と、その強さが 60 dB 減少する時間との時間間隔である。
  • 拡散。後期リバーブの 1 秒あたりのエコー数に比例する。実装によって、リバーブ ディケイに従って密度は変化する。DirectX では、実装による許容範囲のパーセンテージを設定することによって、アプリケーションでこのプロパティを制御できる。
  • 密度。後期リバーブの 1 Hz あたりの共振数に比例する。密度が低いほど、狭い室内の音のように、うつろな音になる。DirectX では、実装による許容範囲のパーセンテージを設定することによって、アプリケーションでこのプロパティを制御できる。

リバーブ プロパティは DirectSoundFXI3DL2Reverb8 オブジェクトによって表され、環境のパラメータは DSFXI3DL2REVERB 型に含まれている。

DirectX では、山から下水管まで、さまざまなオーディオ環境のリバーブ プロパティを記述する数多くのデフォルトのパラメータ、つまりプリセット値をサポートしている。ほとんどのアプリケーションでは、DirectSoundFXI3DL2Reverb8.SetPreset を使ってこれらの環境のいずれかを選択できる。

カスタム プロパティを設定するには、DirectSoundFXI3DL2Reverb8.SetAllParameters を使用する。現在のプロパティを取得するには、DirectSoundFXI3DL2Reverb8.GetAllParameters を使用する。


フランジ

フランジは、元のシグナルとそのエコーとの間の遅延が非常に短く、時間によって変化するエコー エフェクトである。この結果は、スイーピング サウンドと呼ばれることもある。フランジという用語は、テープ リールの縁 (flange) をつかんで回転速度を変化させていたことに由来する。

このエフェクトは、DirectSoundFXFlanger8 オブジェクトによって表される。そのパラメータは、DSFXFLANGER 型に格納される。


ガーグル

ガーグル エフェクトは、信号の振幅を乗算する。

このエフェクトは、DirectSoundFXGargle8 オブジェクトによって表される。そのパラメータは、DSFXGARGLE 型に格納される。


パラメトリック イコライザ

パラメトリック イコライザは、指定された周波数のシグナルを増幅または減衰させる。

同じバッファに GUID_DSFX_STANDARD_PARAMEQ の複数のインスタンスをを設定することによって、複数のピッチのパラメトリック イコライザ エフェクトを並行して適用できる。これによって、アプリケーションでハードウェア イコライザと同様のトーン コントロールを実現できる。

このエフェクトは、DirectSoundFXParamEq8 オブジェクトによって表される。そのパラメータは、DSFXPARAMEQ 型に格納される。


ウェーブ リバーブ

ウェーブ リバーブは音楽用のエフェクトである。ウェーブ リバーブ DMO は、Microsoft にライセンスされている Waves MaxxVerb テクノロジに基づいている。

このエフェクトは、DirectSoundFXWavesReverb8 オブジェクトによって表される。そのパラメータは、DSFXWAVESREVERB 型に格納される。


バッファ チェーン

サウンドは、必ずしも 1 つのセカンダリ サウンド バッファだけを経由しなくてもよい。オーディオパスのバッファは、ほかのセカンダリ バッファにデータを送ることができる。この処理の利点は、複数のバッファからのサウンドを共有バッファに転送し、そこで共通の 3D パラメータや特殊効果を適用できることである。バッファを共有すると、より効率が高まる。

DirectMusic Producer ファイルに埋め込まれたオーディオパス構成からオーディオパスが作成されたときは、バッファ チェーンが自動的に設定される。詳細については、「オーディオパスの使い方」を参照すること。

DirectX 8.0 は、DirectSound API によるバッファ チェーンの作成をサポートしていない。


アレンジ要素の使い方

ここで説明する内容は、動的なミュージック コンポーネントを DirectX Audio アプリケーションに組み込むためのガイドである。ここでは、コードマップやスタイルなどの要素の基本事項を理解していることを前提としている。これらについて不明な点は、「アレンジ用のミュージック要素」を参照すること。

個々のアレンジ要素を使わずに、DirectMusic Producer のファイルをアプリケーションに組み込むことも可能である。多くのアプリケーションでは、完全に作成されたセグメントのみが使用されている。しかし、個別のコンポーネントを使用することによって、実行時のパフォーマンスをさらに制御することができる。

説明するトピックは、次のとおりである。

  • アレンジ用のミュージック ファイル
  • アレンジ用のプログラミング概要
  • スタイルの使い方
  • モチーフの使い方
  • コードマップの使い方
  • テンプレートの使い方
  • トランジションの使い方


アレンジ用のミュージック ファイル

DirectMusic のアレンジをプログラミングする場合、DirectMusic Producer のようなツールで作成したさまざまなファイルを使う。これらの要素を COM オブジェクトとしてアプリケーションにロードし、それらのオブジェクトを取得する。「オーディオ データのロード」を参照すること。

次の表は、開発者が扱うファイル オブジェクトのタイプを示している。これらのオブジェクトはいずれも、DirectMusicLoader8.LoadBandFromResource など、対応するメソッドからも取得できる。

要素 | DirectMusicLoader8 メソッド | クラス | ファイル タイプ
バンド | LoadBand | DirectMusicBand8 | bnd
コードマップ | LoadChordMap | DirectMusicChordMap8 | cdm
DLS コレクション | LoadCollection | DirectMusicCollection | dls
セグメント | LoadSegment | DirectMusicSegment8 | sgt
スタイル | LoadStyle | DirectMusicStyle8 | sty

注 バンドはスタイルの一部としてオーサリングできるが、その場合、スタイルをロードするときにそれらも自動的にロードされる。同様に、スタイルとバンドはセグメントにオーサリングできる。この場合、これらの要素を別のファイルに分ける必要ない。

ファイルには、ほかのファイルへの参照を含めることができる。スタイルにバンド ファイルへの参照が含まれている場合、ローダーがバンド ファイルを見つけることができれば、スタイルがロードされるときに自動的にバンドもロードされる。


アレンジ用のプログラミング概要

実行時にアレンジされる音楽を実装するときに、既にオーサリングされているオブジェクトをビルディング ブロックとして使用する。オーサーやほかのコンテント プロバイダと相談しながら、小さなビルディング ブロックとして取得するミュージック データを選択することにより、実行時に最も高い柔軟性やバリエーションを実現したり、音楽をより完成された形で定義するために、あらかじめ作成された要素をより多く利用できる。

最大のビルディング ブロックを使って、演奏する音楽についてパフォーマンスに指示しなければならない情報のすべてが含まれている、高度に構造化されたセグメント (スタイル ベースまたは MIDI ベース) をロードする。必要な処理は、DirectMusicLoader8.LoadSegment または DirectMusicLoader8.LoadSegmentFromResource メソッドを使ってセグメントをロードすることだけである。次に、返された DirectMusicSegment8 オブジェクトを DirectMusicPerformance8.PlaySegmentEx メソッドに渡す。スタイル再生エンジンは、スタイルからパターン バリエーションを選択し、固定コード進行に従ってこれらを演奏する。また、MIDI ベースのセグメントの場合は、MIDI シーケンスを演奏する。バンド チェンジは、通常、セグメントに含まれる。

より小さなビルディング ブロックを使う場合は、次の要素を取得する。

  • コードマップ。コード進行のロード マップを表す。
  • スタイル。基本的なメロディやリズムと共に、バリエーション、モチーフ、および装飾を定義する。
  • テンプレート セグメント。構造的な計画であり、セグメントの長さ、ループの有無、グルーブ レベルの変更や装飾を配置する場所、コードマップでサインポストの役割を果たすコードのタイプを含め、再生のさまざまな側面を制御する。

DirectMusicComposer8.ComposeSegmentFromTemplate メソッドを使って、コードマップ、スタイル、およびテンプレートを組み合わせ、セグメントを構築する。

実行時の音楽アレンジをより柔軟に行うには、DirectMusicComposer8.ComposeSegmentFromShape メソッドを使って、テンプレートではなく定義済みのシェイプに基づくセグメントを作成する。シェイプは、コマンドおよびサインポスト トラックの作成に使用され、装飾パターン、コード進行、およびコード変更の頻度の選択を制御する。

セグメントを演奏するときに、パートの演奏に使用するバンドを制御することもできる。バンドは通常、スタイルおよびテンプレートにオーサリングされるが、個別のファイルとして提供することもできる。バンドを動的に変更するには、DirectMusicBand8.CreateSegment メソッドを使って、バンドだけから成るセカンダリ セグメントを作成し、音色や音色の設定をプライマリ セグメントに割り当てるときに、このセカンダリ セグメントを演奏する。詳細については、「バンドの使い方」を参照すること。


スタイルの使い方

DirectMusic スタイル オブジェクトは、音楽パターンの集まりを表す。通常は、装飾とモチーフ、拍子記号、テンポ、およびバンドが含まれる。基本的なリズムと、各音色パートで演奏されるノートが定義される。

概念については、「スタイル」を参照すること。

スタイル単独では、実行時にミュージック セグメントを作成するのに十分な情報を備えていない。このため、スタイルのほかに 2 つのコンポーネントが必要となる。コードマップ (コード進行のマップ) と、演奏時にグルーブ レベルと装飾を設定するコマンド トラックである。コマンド トラックはテンプレートから取り出すか、実行時にシェイプから生成する。コードマップは、通常はコードマップ ファイルかリソースから取得する。

テンプレートに基づき、コマンド トラックを使ってセグメントを作成するには、DirectMusicComposer8.ComposeSegmentFromTemplate メソッドを呼び出す。「テンプレートの使い方」を参照すること。

シェイプに基づいてセグメントを作成するには、DirectMusicComposer8.ComposeSegmentFromShape メソッドを呼び出す。スタイルとコードマップへのポインタを指定する。また、コード変更の頻度を制御する和音進行のレート、およびグルーブ レベルと装飾の進行を決定するシェイプ定数も指定する。


モチーフの使い方

モチーフとは、通常はインタラクティブ イベントに応じて演奏されるもので、基本的なスタイル パターン上で演奏されることを意図した、スタイル内の特種なパターンである。モチーフには、ほかのパターンと同様の複雑さを与えることができる。また、バリエーションや複数の音色パートを備えることも可能であるが、通常はさまざまなバックグラウンド パターンと組み合わせても適切に聞こえる、短い単純な音型である。カスタム DLS 音色で演奏するサウンド エフェクトにもなる。

どのモチーフもスタイルの一部としてオーサリングされるので、スタイルをロードするとすぐにモチーフを利用できる。特定のモチーフを再生できるようにするには、DirectMusicStyle8.GetMotif メソッドを呼び出し、モチーフの名前を渡す。この情報はスタイルのドキュメントで確認するか、DirectMusicStyle8.GetMotifName メソッドを使ってインデックス値から取得する。

次のサンプル コードでは、スタイルの最初のモチーフを取得して演奏している。

' style は DirectMusicStyle8 である。
' perf は DirectMusicPerformance8 である。

Dim MotifName As String
Dim segMotif As DirectMusicSegment8

MotifName = style.GetMotifName(1)
Set segMotif = style.GetMotif(MotifName)
Call perf.PlaySegmentEx(segMotif, DMUS_SEGF_SECONDARY, 0)

通常、モチーフはプライマリ セグメントに重ねて演奏されるため、segMotif はセカンダリ セグメントとして演奏される点に注意すること。モチーフにはコード トラックやバンド トラックがないため、これをプライマリ セグメントとして演奏することはできない。無音の状態のときにモチーフを演奏する場合は、スタイルから空白のパターンだけを含むプライマリ セグメントを作成し、モチーフを演奏する間、このセグメントを演奏しておく。


コードマップの使い方

コードマップ オブジェクトは、基礎となる和音構造と音楽の雰囲気を提供するコードのコレクションを表す。コードマップには、多くの関連するコードによるいくつかのパスが含まれ、コンポーザ エンジンが音楽のピースのコード進行を決定する際に、さまざまな選択が可能となる。

概念については、「コードマップ」を参照すること。

オーサリングされたセグメントの場合、通常、アプリケーションはコードマップに関与する必要はない。コードマップは、固定コード進行を作成するために、オーサリングの段階で使用される。ただし、コードマップを使って、実行時にセグメントを作成したり、既存のセグメントのコード進行を変更することもできる。

DirectMusicComposer8.ComposeSegmentFromTemplate または DirectMusicComposer8.ComposeSegmentFromShape メソッドを使ってセグメントを作成するときに、アレンジ用のコードマップを設定する。詳細については、「スタイルの使い方」を参照すること。

セグメントを作成した後で、DirectMusicComposer8.ChangeChordMap メソッドを呼び出して、いつでもコードマップを変更できる。これにより、基本的なリズムやメロディを変えることなく、音楽の雰囲気を変更する効果がある。


テンプレートの使い方

テンプレートは、演奏可能な音楽のセグメントを実行時にアレンジするときに使用できるセグメントである。テンプレートは、セグメントの長さとループ ポイントを設定する。コマンド トラックが提供され、グルーブ レベルの変更や、装飾パターンの選択が制御される。また、新しいコードをそれぞれどのサインポスト グループから取得するかを指定して、セグメントをアレンジするときにコードマップをどのように使用するかも指示する。

概念については、「テンプレート」を参照すること。

各テンプレートはDirectMusicSegment8 オブジェクトによって表される。

テンプレートを取得する方法は 2 つある。

  • DirectMusicLoader8.LoadSegment または DirectMusicLoader8.LoadSegmentFromResource メソッドを使って、テンプレート ファイルまたはリソースからテンプレートをロードする。
  • DirectMusicComposer8.ComposeTemplateFromShape メソッドを使って、シェイプからテンプレートを作成する。テンプレートの長さ、全体のシェイプ、イントロとエンドの装飾パターンを演奏するかどうか、およびエンディングの長さを選択する。

テンプレート セグメント オブジェクトを取得した後、スタイルやコードマップへのポインタと共に、そのオブジェクトを DirectMusicComposer8.ComposeSegmentFromTemplate メソッドに渡せる。また、コード変更の頻度を設定する和音進行も指定する。ComposeSegmentFromTemplate メソッドは、DirectMusicPerformance8.PlaySegmentEx メソッドに渡せるセグメントを作成する。


トランジションの使い方

あるセグメントを停止して次のセグメントを始める際に、耳障りな中断が突然発生することを防止するため、または音楽を終止形 (カデンツァ) へ移行するために、適切なトランジションを提供する中間または終始のセグメントを作成するようコンポーザに指示できる。

トランジション セグメントをアレンジするには、3 つの手法のいずれかを選択できる。

  • DirectMusicPerformance8.PlaySegmentEx メソッドを使うと、Transition パラメータでセグメントを指定できる。このセグメントは、新しくアレンジするトランジションのテンプレートとして使用される。トランジションは startTime で演奏され、Source で指定されたセグメントが演奏される。
  • DirectMusicComposer8.AutoTransition メソッドは、DirectMusicPerformance8 オブジェクトを受け取り、現在演奏中のセグメントから開発者が指定した 2 番目のセグメントへのトランジションを作成する。続いて、再生の目的でトランジション セグメントと 2 番目のセグメントを自動的に挿入する。トランジションの演奏は、直ちに、または IFlags パラメータで指定された次の境界から開始される。オプションで、2 番目のセグメントを Nothing にもできるが、その場合はトランジションを経て無音に至る。
  • DirectMusicComposer8.ComposeTransition メソッドは、1 番目のセグメントの任意の場所から 2 番目のセグメントの先頭または無音に至るトランジションを作成し、アプリケーションが移行を演奏できるように DirectMusicSegment8 オブジェクトを返す。

AutoTransition と ComposeTransition のどちらのメソッドもパラメータとして、コードマップ、コマンド、および一連のフラグを受け取る。

  • コードマップは、通常どおり、セグメントのコード進行を定義するコード トラックを作成するために使用される。
  • コマンドとして、CONST_DMUS_COMMANDT_TYPES 列挙型のいずれかを指定する。コマンドは、トランジション セグメントのコマンド トラックで要求するパターンのタイプとして、通常のグルーブ パターンと装飾のどちらを使うかを決定する。セグメントを演奏する際に、スタイルから適切なパターンが選択される。
  • CONST_DMUS_COMPOSEF_FLAGS からフラグを選択し、トランジションの詳細、特にそのタイミングを定義する。DMUS_COMPOSEF_MODULATE フラグを使って、トランジションをある調性から別の調性へ円滑に移行させる。2 番目のセグメントがない場合、無音への変調は不可能なので、このフラグは利用できない。

AutoTransition およびmposeTransition によって作成されたトランジションの長さは、通常 1 小節である。ただし、DMUS_COMPOSEF_LONG フラグが含まれ、スタイル内のエンド装飾が 1 小節よりも長い場合は、1 小節よりも長くなる。また、DMUS_COMMANDT_ENDANDINTRO 型の場合は 2 小節以上になる。


トラックのアレンジ

セグメント内のほとんどのトラックは固定されており、セグメントを演奏するたびに同じデータが生成される。ただし、トラックが 適切に設定されている場合、演奏の開始時やループするたびに、動的にデータを生成できる。

サインポスト トラックである単一の標準トラックは、アレンジをサポートする。サインポスト トラックは、コードマップから新しいコード トラックをアレンジする。


オーディオ スクリプトの使い方

スクリプトは、DirectMusic Producer など、スクリプト エディタを含むアプリケーションでオーサリングされたオブジェクトである。スクリプトは主にテキストで構成されるが、スクリプト オブジェクトにはいくつかのバイナリ パラメータも含まれている。

DirectX for Visual Basic では、アプリケーションが API を使ってオーディオ スクリプトのロードおよび呼び出しを行うことはできない。ただし、DirectMusic Producer で作成するセグメントにスクリプト トラックを含めて、スクリプト内のルーチンの呼び出しをトリガすることができる。


DirectSound でのウェーブの再生

ここでは、DirectMusic ローダーおよびパフォーマンス オブジェクトで提供されるサービスを使用せずに、DirectSound バッファを使ってウェーブを再生する方法について説明する。

DirectX 8.0 以降用に作成されたほとんどのアプリケーションでは、ウェーブ サウンドを再生する最適な方法は、ウェーブ サウンドをセグメントとしてロードし、パフォーマンスで再生することである。こうすることによって、コードが少なくなり、サウンド エフェクトとミュージックを密接に統合でき、3D バッファに入れる前に、オーディオパス上のサウンドをミキシングするなどの高度な機能を利用できる。ただし、ウェーブ サウンドを直接バッファで再生することもできる。

詳細については、次のトピックを参照すること。

  • DirectSound の再生の概要
  • DirectSound デバイス
  • DirectSound バッファ
  • ウェーブ データの使い方
  • DirectSound でのエフェクトの使い方


DirectSound の再生の概要

DirectSound オブジェクトはデバイスを表し、そのデバイスを管理し、サウンド バッファを作成するために使用される。

1 つのサウンド デバイスに対して複数のアプリケーションが DirectSound オブジェクトを作成することができる。入力フォーカスがあるアプリケーションからほかのアプリケーションへ移動する際に、オーディオ出力はあるアプリケーションのストリームからほかのアプリケーションのストリームへと自動的に切り替わる。したがって、入力フォーカスが移動する際に、アプリケーションはバッファの再生と停止を繰り返す必要はない。

DirectSound バッファ オブジェクトは、サウンド データを保持するバッファを表す。バッファ オブジェクトは、サウンドの再生の開始、停止、一時停止、周波数やフォーマットなどの属性を設定するために使われる。

プライマリ サウンド バッファは、リスナーが実際に聞くオーディオを保持する。各セカンダリ サウンド バッファは、1 つのサウンドまたはオーディオ ストリームを保持する。DirectSound は自動的にプライマリ バッファを作成するが、セカンダリ バッファはアプリケーションが作成しなければならない。セカンダリ バッファ内のサウンドが再生されると、DirectSound はプライマリ バッファ内でこれらをミキシングし、出力デバイスへ送り出す。DirectSound がミキシングできるバッファ数は処理時間にのみ制限され、処理時間が許す限りミキシングすることができる。

短いサウンドは全体をバッファにロードし、いつでも単純なメソッドの呼び出しによって再生できる。長いサウンドはストリーミングする必要がある。アプリケーションでは、再生カーソルの位置をポーリングしたり、再生カーソルが特定の位置に到達したときに通知を要求することによって、バッファに入れるデータをストリーミングしなければならない時期を確認できる。

DirectX for Visual Basic には、ウェーブ ファイルやリソースから完全なサウンドを自動的にロードするサウンド バッファを作成するためのメソッドが用意されている。長いサウンドの場合は、アプリケーションで解析やストリーミングを処理しなければならない。


DirectSound デバイス

アプリケーションにDirectSound を実装する最初のステップは、サウンド デバイスを表す DirectSound オブジェクトを作成することである。

ここでは、利用可能なサウンド デバイスの列挙、デバイスに対する DirectSound オブジェクトの作成、オブジェクトのメソッドを使った協調レベルの設定、デバイス能力の取得、サウンド バッファの作成、システム スピーカの構成、ハードウェア メモリの圧縮をアプリケーションが行う方法について説明する。

  • サウンド デバイスの列挙
  • DirectSound オブジェクトの作成
  • 協調レベル
  • デバイスの能力
  • スピーカの構成
  • ハードウェア メモリの圧縮


サウンド デバイスの列挙

ユーザーが好む再生装置で単純にサウンドを再生するだけのアプリケーションでは、利用可能なデバイスを列挙する必要はない。DirectX8.DirectSoundCreate 関数を呼び出して DirectSound8 オブジェクトを作成する場合、デフォルトのデバイスを指定できる。詳細については、「DirectSound オブジェクトの作成」を参照すること。

特定の種類のデバイスを探している場合や、ユーザーにデバイスを選択させる場合、複数のデバイスを使って動作する必要がある場合は、システム上で利用可能なデバイスを列挙しなければならない。

列挙は 3 つの目的で使われる。

  • 利用可能なハードウェアを報告。
  • 各デバイスに GUID を供給。
  • 列挙された各デバイスについて一時的な DirectSound オブジェクトを作成し、デバイスの能力をチェックできるようにする。

デバイスを列挙するには、まず DirectX8.GetDSEnum メソッドを呼び出す必要がある。このメソッドは、DirectSound に対応したデバイスのコレクションを含む DirectSoundEnum8 オブジェクトを作成する。利用可能なデバイス数を決定するには、DirectSoundEnum8.GetCount メソッドを呼び出す。各デバイスの情報は、DirectSoundEnum8.GetDescription、DirectSoundEnum8.GetGuid、および DirectSoundEnum8.GetName の各メソッドから返される。これらのメソッドはそれぞれパラメータとしてコレクション内のデバイスのインデックスを取る。

次のサンプル アプリケーションは、各サウンド デバイスの説明を出力する。

Dim dx As New DirectX8
Dim dsenum As DirectSoundEnum8

Private Sub Form_Load()
  Set dsenum = dx.GetDSEnum
  For x = 1 To dsenum.GetCount
    Debug.Print dsenum.GetDescription(x), " ",
  Next x
End Sub

注 列挙された最初のデバイスは常に "プライマリ サウンド ドライバ" と呼ばれ、GUID はすべて 0 である。このデバイスは、ユーザーがコントロール パネルで設定した優先する再生デバイスを表す。アプリケーションが "プライマリ サウンド ドライバ" を一覧に追加して、ユーザーにデバイスの選択肢を提供しやすくするために、このデバイスは別に列挙される。プライマリ デバイスは、適切な名前および GUID と共に列挙される。


DirectSound オブジェクトの作成

DirectX8.DirectSoundCreate メソッドを使って DirectSound8 オブジェクトを作成する。単一のパラメータで、このオブジェクトに関連付けるデバイスの GUID を指定する。この GUID は、サウンド デバイスの列挙で取得できる。または、次のいずれかの GUID を渡してデフォルトのデバイスを指定する。

DSDEVID_DEFAULTPLAYBACK
デフォルトのシステム オーディオ デバイス。デバイスの GUID パラメータで vbNullString を渡すことによって、このデバイスを指定することもできる。デフォルトのデバイスは、 "プライマリ DirectSound ドライバ" として列挙される。
DSDEVID_DEFAULTVOICEPLAYBACK
デフォルトの音声通信デバイス。これは、通常、USB マイク付きヘッドセットなどのセカンダリ デバイスである。

サウンド デバイスが存在しない場合や、ウェーブフォーム オーディオ関数 (DirectSound ではない) を利用するアプリケーションがサウンド デバイスを制御している場合は、この作成メソッドはエラーとなる。アプリケーションはこの呼び出しが失敗した場合に備えて、サウンドなしでアプリケーションを続行するか、既にサウンド デバイスを使っているアプリケーションを閉じるようユーザーにプロンプトを表示するか、どちらかの準備をする必要がある。

次のサンプル コードでは、デフォルトのシステム デバイスを使用する DirectSound8 オブジェクトを作成している。

Dim m_dx As New DirectX8
Dim m_ds As DirectSound8
Set m_ds = m_dx.DirectSoundCreate(vbNullString)


協調レベル

Windows はマルチタスク環境なので、複数のアプリケーションが任意の時点で同じデバイス ドライバを使って動作することがある。DirectX は協調レベルを使って、各アプリケーションが不適切な方法または不適切なタイミングでデバイスにアクセスしないことを保証する。DirectSound の各アプリケーションは、デバイスに対して認められるアクセス範囲を決定する 1 つの協調レベルを持つ。

DirectSound8 オブジェクトを作成した後で、サウンドを再生する前に DirectSound8.SetCooperativeLevel メソッドを使ってデバイスの協調レベルを設定しなければならない。

次の Visual Basic の例では、DirectSound8 オブジェクト m_ds の協調レベルを設定している。hwnd 引数は、アプリケーション ウインドウへのハンドルである。

m_ds.SetCooperativeLevel Me.hWnd, DSSCL_PRIORITY

DirectSound では、DSSCL_NORMAL、DSSCL_PRIORITY、および DSSCL_WRITEPRIMARY の値で表される 3 つのサウンド デバイスの協調レベルを定義している。

注 DirectX 8.0 以前のバージョンで利用可能であった協調レベル DSSCL_EXCLUSIVE は廃止された。DirectX アプリケーションでほかのアプリケーションをミュートすることはできなくなった。排他的レベルを要求するアプリケーションには、代わりに優先レベルが付与される。

標準協調レベル

標準協調レベルでは、アプリケーションは、プライマリ サウンド バッファのフォーマットの設定、プライマリ バッファへの書き込み、デバイスのオンボード メモリの圧縮が行えない。この協調レベルを使うすべてのアプリケーションは、22kHz、ステレオ サウンド、8 ビット サンプリングのプライマリ バッファ フォーマットを使うので、デバイスはアプリケーション間で最も円滑に切り替えられる。

優先協調レベル

優先協調レベルで DirectSound デバイスを使うと、アプリケーションはハードウェア ミキシングなどのハードウェア リソースに対して最高の権限を確保し、プライマリ サウンド バッファのフォーマットの設定、デバイスのオンボード メモリの圧縮を行える。

ゲーム アプリケーションは、ほとんどすべての環境で優先協調レベルを使用する。このレベルは、サンプリング レートとビット深度に対するアプリケーション制御を可能にしながら、最も強力に動作する。また、優先協調レベルでは、IP テレフォニなどのほかのアプリケーションからのオーディオをゲームからのオーディオと共に聞くこともできる。

書き込み優先協調レベル

Visual Basic アプリケーションでは、DSSCL_WRITEPRIMARY 協調レベルを使うべきではない。このレベルは、DirectSound ミキサを使用しない特殊なアプリケーション用である。


デバイスの能力

DirectSound を使うと、アプリケーションはサウンド デバイスのハードウェア能力を取得できる。DirectSound は利用可能なハードウェア アクセラレーションを自動的に利用するので、アプリケーションでは、通常この取得を行う必要はない。しかし高性能のアプリケーションはこの情報を利用し、利用可能なハードウェアに対してサウンドの要求事項を評価できる。たとえば、ハードウェア ミキシングが利用可能な場合は、利用不可能な場合に比べて、アプリケーションがより多くのサウンドを再生できるはずである。

DirectX8.DirectSoundCreate メソッドを呼び出して DirectSound8 オブジェクトを作成した後は、DirectSound8.GetCaps メソッドを使ってサウンド デバイスの能力を取得できる。

次の例では、DirectSound8 オブジェクト m_ds によって表されるデバイスの能力を取得している。

Dim caps As DSCAPS
m_ds.GetCaps caps

DSCAPS 型は、サウンド デバイスの能力とリソースに関する情報を受け取るが、この中にはタイプごとの最大のリソースと現在利用可能なリソースが含まれる。

アプリケーションがハードウェア能力を評価する場合は、バッファ割り当てを行うたびに DirectSound8.GetCaps メソッドを呼び出して、次のバッファを作成するのに十分なリソースがあるかどうかを確認すべきである。


スピーカの構成

DirectSound は、スピーカがリスナーに対する相対的な位置をとるスピーカ構成を使って、ユーザーのサウンド システムに合わせて 3D エフェクトを最適化する。

Windows 98 と Windows 2000 では、ユーザーはコントロール パネルを使ってスピーカ構成を設定できる。アプリケーションは DirectSound8.GetSpeakerConfig を使ってこの値を取得し、DirectSound8.SetSpeakerConfig を呼び出してその値を変更できる。

SetSpeakerConfig がすぐに有効になるという保証はなく、単にレジストリ設定を変更しただけで、コンピュータを再起動しなければ有効にならない場合もある。このメソッドを使用する代わりに、コントロール パネルを使ってスピーカ構成を変更するようユーザーにアドバイスする必要がある。

Windows 95 では、GetSpeakerConfig は単純に、デフォルトの値または SetSpeakerConfig で設定した直前の値を返す。


ハードウェア メモリの圧縮

ここでは、C++ でのアプリケーション開発について説明する。


DirectSound バッファ

DirectSound バッファ オブジェクトは、ウェーブ データの入力から出力までの配信を制御する。入力には、シンセサイザ、ほかのバッファ、ファイル、またはリソースがある。ほとんどのバッファの場合、出力先はプライマリ バッファと呼ばれるミキシング エンジンである。データは、プライマリ バッファから、PCM サンプルをサウンド ウェーブに変換するハードウェアに送られる。

ここでは、以前のバージョンの DirectSound 用に作成されたアプリケーション、つまりバッファの下位レベルの制御を必要とするアプリケーションについて説明する。アプリケーションが DirectMusic パフォーマンス オブジェクトを使ってサウンドを再生する場合、バッファの作成および管理は自動的に行われる。ただし、3D エフェクトや DMO のエフェクトのパラメータへのアクセスを取得するために、バッファ オブジェクトを取得できる。詳細については、「エフェクトの使い方」および「3D サウンド」を参照すること。

DirectSound バッファの使い方については、以下のトピックで説明する。

  • バッファの基本
  • セカンダリ バッファの作成
  • バッファの複製
  • バッファ コントロール オプション
  • バッファの 3D アルゴリズム
  • スタティック バッファの書き込みと再生
  • ストリーム バッファの使い方
  • 再生のコントロール
  • 再生カーソルと書き込みカーソル
  • 再生バッファの通知
  • サウンドのミキシング
  • バッファ管理

キャプチャ バッファについては、「ウェーブのキャプチャ」を参照すること。


バッファの基本

DirectSound を初期化すると、DirectSound はサウンドのミキシングと出力デバイスへの送信をするために、プライマリ サウンド バッファの作成と管理を自動的に行う。

アプリケーションは、個々のサウンドの保存と再生をするために、少なくとも 1 つのセカンダリ サウンド バッファを作成しなければならない。この方法の詳細については、「セカンダリ バッファの作成」を参照すること。

セカンダリ バッファは、アプリケーションが動作している間常に持続することも、不要になったときに削除することもできる。セカンダリ バッファには、ゲーム中の効果音など繰り返し再生される 1 つのサウンドを格納したり、適宜新しいデータを記録することもできる。アプリケーションは、セカンダリ バッファに記憶されているサウンドを 1 つのイベント、または連続再生されるループ サウンドとして再生できる。サウンド ファイルのデータが非常に大きく、メモリに記憶しておくことが実用的ではない場合、データをストリームするためにセカンダリ バッファを利用できる。

バッファは、ハードウェアまたはソフトウェアのいずれかに配置できる。ハードウェア バッファはサウンド カードのプロセッサによってミキシングされ、ソフトウェア バッファは CPU によってミキシングされる。ソフトウェア バッファのデータは常にシステム メモリに置かれる。ハードウェア バッファのデータはシステム メモリに置くことも、アプリケーションが要求し、リソースが使用可能な場合はオンボード メモリに置くこともできる。詳細については、「ダイナミック ボイス管理」および「ISA および PCI カードでのハードウェア アクセラレーション」を参照すること。

異なるセカンダリ バッファのサウンドは、これらを同時に再生するだけでミキシングできる。処理能力の限界内であれば、任意の数のセカンダリ バッファを同時に再生できる。


セカンダリ バッファの作成

セカンダリ サウンド バッファを作成するには、DirectSound8.CreateSoundBuffer、DirectSound8.CreateSoundBufferFromFile、または DirectSound8.CreateSoundBufferFromResource メソッドを呼び出す。これらのメソッドは DirectSoundSecondaryBuffer8 オブジェクトを作成する。このオブジェクトを使って、バッファを操作および演奏できる。

CreateSoundBufferFromFile と CreateSoundBufferFromResource は、サウンドがそれほど長くない場合に使うのに適したメソッドである。DirectSound は、サウンド全体を保持するのに十分なバッファを作成し、ウェーブ フォーマットをデータのフォーマットに適合させ、バッファにデータを書き込む。CreateSoundBuffer はストリーム バッファに適しているが、開発者がウェーブ ファイルやリソースを解析し、バッファに対するデータのストリーミング処理を行わなければならない。

ストリーム バッファを作成する場合は、常に DSBUFFERDESC 型に DSBCAPS_GETCURRENTPOSITION2 フラグを指定する。

次の例では、2 秒間のデータを保持できるストリーム バッファを作成する方法を示している。m_ds 変数は DirectSound8 オブジェクトに設定されていると仮定する。

Dim m_dsb As DirectSoundSecondaryBuffer8

Public Sub CreateSoundBuffer()

  Dim buffdesc As DSBUFFERDESC

  ' 作成するサウンド バッファを記述する。

  With buffdesc
    lFlags = DSBCAPS_CTRLPAN Or DSBCAPS_CTRLVOLUME _
          Or DSBCAPS_CTRLFREQUENCY

    With .fxFormat
      .nFormatTag = WAVE_FORMAT_PCM
      .nChannels = 2
      .lSamplesPerSec = 22050
      .nBitsPerSample = 16
      .nBlockAlign = (.nChannels * .nBitsPerSample) / 8
      .lAvgBytesPerSec = .lSamplesPerSec * .nBlockAlign
      .nSize = 0    ' WAVE_FORMAT_PCM の場合は無視される。
    End With

    lBufferBytes = .fxFormat.lAvgBytesPerSec * 2

  End With

  Set m_dsb = ds.CreateSoundBuffer(buffdesc)

End Sub

次の例に示すように、ファイルやリソースからバッファを作成する方法はより簡単である。

Dim m_dsb As DirectSoundSecondaryBuffer8
Dim buffdesc As DSBUFFERDESC

buffdesc.lFlags = DSBCAPS_CTRLPAN Or DSBCAPS_CTRLVOLUME _
  Or DSBCAPS_CTRLFREQUENCY
Set dsbuffer = ds.CreateSoundBufferFromFile( _
  "c:\media\ding.wav", dsbdesc)

この場合、バッファのフォーマットはデータのフォーマットに基づき、メソッドはこの情報を dsbdesc.fxFormat に配置する。

DirectSound はハードウェア リソースを最初のバッファに割り当て、その利点を生かす。ハードウェア バッファはサウンド カード プロセッサでミキシングされるので、アプリケーション性能にほとんど影響を及ぼさない。

バッファの位置を DirectSound に決めさせずに自分で指定したい場合は、DSBUFFERDESC 型に DSBCAPS_LOCHARDWARE または DSBCAPS_LOCSOFTWARE のどちらかのフラグを設定する。DSBCAPS_LOCHARDWARE フラグを設定し、ハードウェア リソースが不足している場合、バッファの作成要求は失敗する。

DirectSound のボイス管理機能を利用するには、バッファの作成時に DSBCAPS_LOCDEFER フラグを指定する。このフラグは、バッファに対するリソースの割り当てを、バッファが再生されるまで遅延する。詳細については、「ダイナミック ボイス管理」を参照すること。

既存のバッファの位置を確認するには、DirectSoundSecondaryBuffer8.GetCaps メソッドを使い、DSBCAPS 型の lFlags メンバをチェックして、DSBCAPS_LOCHARDWARE と DSBCAPS_LOCSOFTWARE のどちらのフラグになっているかを調べる。どちらかが必ず指定されている。

DSBCAPS_STATIC フラグを設定すると、可能な場合はバッファをオンボードのハードウェア メモリに作成すべきであることが DirectSound に通知される。ハードウェア バッファが利用できない場合でも、バッファ作成メソッドは失敗しない。このフラグは、バッファ用にシステム メモリを使う最近のサウンド カードの多くには影響しない。ハードウェア スタティック バッファは、繰り返し再生される短いサウンドに対してだけ使うべきである。詳細については、「ISA および PCI カードでのボイス管理」を参照すること。


バッファの複製

DirectSound8.DuplicateSoundBuffer メソッドを使って、同じデータを含む複数のセカンダリ バッファを作成できる。プライマリ サウンド バッファは複製できない。たとえ呼び出しが成功したとしても、実際に重複バッファが元のバッファとメモリを共有するとは限らないので、これらの変更がすべての重複バッファに反映されるであろうという予測のもとにバッファを変更するべきではない。


バッファ コントロール オプション

サウンド バッファを作成するときに、バッファが必要とするコントロール オプションを指定しなければならない。これには DSBUFFERDESC 型の lFlags メンバを使用する。この構造体は、1 つまたは複数の DSBCAPS_CTRL* フラグを保持できる。

次のコントロールが利用できる。

  • 3D プロパティ。
  • エフェクト。
  • 周波数。
  • パン。
  • ボリューム。
  • 位置の通知。

あらゆるサウンド カードから最高の性能を得るには、アプリケーションが使うオプションだけを指定すべきである。

DirectSound はコントロール オプションを使って、サウンド バッファにハードウェア リソースを割り当てられるかどうかを決定する。たとえば、あるデバイスがハードウェア バッファをサポートしていて、それらのバッファにパン コントロールを提供していないとする。この場合、DirectSound は DSBCAPS_CTRLPAN フラグが指定されていない場合に限って、ハードウェア アクセラレーションを使う。

コントロールは、特定の組み合わせで使用できないことに注意すること。たとえば、パンと 3D を同時に使用することはできない。

バッファが備えていないコントロールを使おうとすると、メソッドは失敗する。たとえば、DirectSoundSecondaryBuffer8.SetVolume メソッドを使ってボリュームを変更しようとするとき、そのバッファの作成時に DSBCAPS_CTRLVOLUME フラグが指定されていた場合に限ってメソッドは成功する。このフラグが指定されていなかった場合はメソッドは失敗に終わり、DSERR_CONTROLUNAVAIL エラー値が返される。

「再生のコントロール」も参照すること。


バッファの 3D アルゴリズム

DSBCAPS_CTRL3D コントロール フラグを指定してセカンダリ フバッファを作成するときに、バッファがソフトウェアで処理される場合は、サウンドの空間的な広がりを出すために使用するアルゴリズムも指定できる。デフォルトでは、HRTF 処理は実行されず、リスナーから相対的なサウンドの位置は、パンおよびボリュームによってのみ指定される。バッファに 2 つのレベルの HRTF を要求できる。

詳細については、「DSBUFFERDESC」を参照すること。


スタティック バッファの書き込みと再生

独立したサウンド全体を保持するセカンダリ バッファを、スタティック バッファという。同じバッファを異なるサウンドで再利用することもできるが、通常はデータを一度だけスタティック バッファに記述する。

スタティック バッファはストリーム バッファと同様に作成および管理される。違いはバッファの使い方だけである。スタティック バッファは一度書き込まれて演奏されるが、ストリーム バッファは演奏中に定期的にデータが更新される。

注 スタティック バッファは必ずしも、DSBCAPS_STATIC フラグをバッファ記述に設定することで作成されるわけではない。このフラグは、現在の多くのハードウェアでは使用できない、サウンド カード上でのメモリ割り当てを要求する。スタティック バッファはシステム メモリ内に置かれ、DSBCAPS_LOCHARDWARE または DSBCAPS_LOCSOFTWARE のどちらかのフラグで作成される。詳細については、「ISA および PCI カードでのボイス管理」を参照すること。

スタティック バッファは、DirectSound8.CreateSoundBufferFromFile または DirectSound8.CreateSoundBufferFromResource のどちらかのメソッドの呼び出しを使って作成され、データが書き込まれる。

次のサンプル コードは、リソース ファイルで "bounce" として識別されるウェーブからスタティック バッファを作成する。m_ds は DirectSound8 オブジェクトと仮定する。

Dim dsbd As DSBUFFERDESC
Dim dsbBounce As DirectSoundSecondaryBuffer8

dsbd.lFlags = DSBCAPS_CTRLVOLUME
Set dsbBounce = m_ds.CreateSoundBufferFromResource( _
        vbNullString, "bounce", dsbd)

リソース ファイルは実行可能ファイルにコンパイルされているので、モジュール名を与える必要はない。同様に、メソッドがデータのサイズからバッファのサイズを決定するので、DSBUFFERDESC 型の lBufferBytes メンバの値も設定する必要はない。WAVEFORMATEX 型は、リソースに格納されたヘッダーからウェーブ フォーマットについての情報を受け取る。

バッファを再生するには、次のように DirectSoundSecondaryBuffer8.Play を呼び出す。

dsbResource.SetCurrentPosition 0
dsbResource.Play 0

この例では DSBPLAY_LOOPING フラグを設定していないので、バッファは最後に到達すると自動的に停止する。また、DirectSoundSecondaryBuffer8.Stop を使うとバッファを早めに停止できる。バッファを早めに停止する場合は、再生カーソルがその場所にとどまる。したがって、例の DirectSoundSecondaryBuffer8.SetCurrentPosition に対する呼び出しは、バッファが始めから開始することを保証するものである。

また、DirectSound8.CreateSoundBuffer を使って空のスタティック バッファを作成した後、DirectSoundSecondaryBuffer8.WriteBuffer メソッドを使ってメモリのほかの位置からデータを書き込むこともできる。

セカンダリ バッファへの書き込みについては、「ストリーム バッファの使い方」を参照すること。


ストリーム バッファの使い方

ストリーム バッファは、一度にバッファに収まらない長いサウンドを再生する。バッファが再生されるにつれ、古いデータは定期的に新しいデータに置き換わる。

ストリーム バッファを再生するには、flags パラメータに DSBPLAY_LOOPING を指定して DirectSoundSecondaryBuffer8.Play メソッドを呼び出す。

再生を停止するには、DirectSoundSecondaryBuffer8.Stop メソッドを呼び出す。このメソッドはバッファを即時に停止するので、すべてのデータが再生されたことを確認する必要がある。これを行うには、再生位置をポーリングするか、通知位置を設定する。

データをバッファにストリーミングするには、DirectSoundSecondaryBuffer8.WriteBuffer メソッドを使う。このメソッドによって、バッファの任意の部分にデータを書き込むことができる。バッファ全体に書き込むこともできるが、再生中に行うべきではない。毎回バッファの一部だけをリフレッシュすること。たとえば、再生カーソルが 2/4 に達したらすぐに、バッファの最初の 1/4 をロックして書き込むようにする。バッファの再生カーソルと書き込みカーソルの間にある部分には書き込んではならない。詳細については、「再生カーソルと書き込みカーソル」を参照すること。

次のサンプル コードは、バイト配列 myBuffer から、dsb で表されたバッファの先頭に 1,000 バイトのデータを書き込む。

dsb.WriteBuffer 0, 1000, myBuffer(0), DSBLOCK_DEFAULT

WriteBuffer は、ラップ アラウンドを透過的に処理する。たとえば、セカンダリ バッファが 10,000 バイトで作成されており、アプリケーションがバッファの中間を過ぎたオフセットに 5,000 バイト書き込む場合は、次のようになる。

dsb.WriteBuffer 8000, 5000, myBuffer(0), DSBLOCK_DEFAULT

この呼び出しは、バッファの最後に最初の 2,000 バイトを書き込み、バッファの先頭に次の 3,000 バイトを書き込む。

続くデータ記述に対するオフセットを追跡するのは、アプリケーションの責任である。この処理の最も簡単な方法は、通知位置を設定し、イベントがトリガされるたびに固定したバイト数を書き込むことである。

詳細については、次のトピックを参照すること。

  • 再生カーソルと書き込みカーソル
  • 再生バッファの通知
  • ウェーブ ファイルの読み込み


再生のコントロール

DirectSoundSecondaryBuffer8.GetVolume と DirectSoundSecondaryBuffer8.SetVolume の各メソッドを使うと、再生中のバッファのボリュームを取得および設定できる。DirectSoundPrimaryBuffer8 オブジェクトについても、同様のメソッドを使用できる。プライマリ サウンド バッファのボリュームを設定すると、サウンド カードのウェーブフォーム オーディオのボリュームが変更される。

DirectSoundSecondaryBuffer8.GetFrequency と DirectSoundSecondaryBuffer8.SetFrequency の各メソッドを使うと、サンプリング オーディオの再生周波数を取得および設定できる。プライマリ バッファの周波数は変更できない。

パンを取得および設定するには、DirectSoundSecondaryBuffer8.GetPan と DirectSoundSecondaryBuffer8.SetPan の各メソッドを使用する。DirectSoundPrimaryBuffer8 オブジェクトについても、同様のメソッドを使用できる。

これらのコントロールのいずれかを使うには、バッファを作成する際に適切なフラグを設定しなければならない。「バッファ コントロール オプション」を参照すること。


再生カーソルと書き込みカーソル

DirectSound はバッファへのポインタを 2 つ保持している。再生カーソルと書き込みカーソルである。これらの位置はバッファのバイト オフセットであり、メモリの絶対アドレスではない。

DirectSoundSecondaryBuffer8.Play メソッドは、常にバッファの再生カーソルの位置から再生を開始する。バッファを作成した時点で、カーソル位置は 0 に設定される。サウンドが再生されるにつれ、カーソル位置は移動し、次に出力されるデータ バイトを示す。バッファが停止したときは、カーソルは次のデータ バイトにとどまる。

バッファの書き込みカーソルより後の場所には、データを安全に書き込める。カレント プレイ ポジションとカレント ライト ポジションの間にあるブロックは、既に再生が確定していて、安全に変更することはできない。

バッファを時計の文字盤で表し、時計回りの方向にデータを書き込むと考える。再生位置と書き込み位置は、この文字盤上で同じ速度で回転する 2 本の針にたとえられ、書き込み位置は、常に再生位置の少し前方にある。再生位置が 1 を示し、書き込み位置が 2 を示している場合は、データを書き込んでも安全なのは 2 の後だけである。1 と 2 の間のデータは DirectSound が既に再生キューに入れている可能性もあるので、変更すべきではない。

書き込み位置は、バッファに書き込まれたデータではなく再生位置に合わせて移動する。データをストリーミングする場合、次に書き込みを行うデータ ブロックの位置を示すために、開発者は独自のポインタを維持する責任を負う。

アプリケーションは、DirectSoundSecondaryBuffer8.GetCurrentPosition メソッドを呼び出すことにより、再生カーソルと書き込みカーソルを取得できる。DirectSoundSecondaryBuffer8.SetCurrentPosition メソッドによって、再生カーソルを移動できる。アプリケーションは、書き込みカーソルの位置を制御しない。

再生カーソルをできるだけ正確に報告するには、セカンダリ バッファを作成する際に DSBCAPS_GETCURRENTPOSITION2 フラグを指定しなければならない。詳細については、「DSBUFFERDESC」を参照すること。


再生バッファの通知

オーディオをストリーミングする場合、再生カーソルがバッファ内のあるポイントに到達したときや、再生が停止したときに、アプリケーションへの通知を発生させたいことがある。DirectSoundSecondaryBuffer8.SetNotificationPositions メソッドを使うと、イベントのシグナルを送信するポイントをバッファ内にいくつでも設定できる。ただし、バッファの再生中はイベント ポイントの設定を行うことはできない。

バッファに通知イベントを設定するには、バッファのコードを保持するフォームに DirectXEvent8 クラスを最初に実装しなければならない。ドロップダウン クラス リストから DirectXEvent8 を選択して DirectXEvent8.DXCallback メソッドを作成し、イベントが通知されたときに実行するコードを追加する。

DirectX8.CreateEvent メソッドを呼び出してイベント ハンドルを作成し、そのイベントハンドルを DSBPOSITIONNOTIFY 型の hEventNotify メンバに渡す。この型を DirectSoundBuffer8.SetNotificationPositions メソッドに渡す。これで、再生カーソルが特定の位置に到達するたびに、イベント ハンドルが DirectXEvent8.DXCallback に渡される。

ボイス管理を利用している場合は、通知位置に到達する前にバッファを終了できる。DSBPOSITIONNOTIFY の「注意」を参照すること。

次のコードの例は、単一の通知位置の設定方法を示している。以下は、モジュールの宣言セクションの行である。

Implements DirectXEvent8

Dim gDX As New DirectX8
Dim gDSB As DirectSoundSecondaryBuffer8
Dim endEvent As Long
Dim dsbpn(0) As DSBPOSITIONNOTIFY

dsbpn は引数を 1 つしか持っていないが、配列でなくてはならないことに注意すること。

Form_Load サブルーチンで、イベントが作成される。

endEvent = gDX.CreateEvent(Me)

DirectSoundSecondaryBuffer8 オブジェクトの作成後、通知位置が設定され、次のようにイベントに関連付けられる。

With dsbpbn(0)
  .hEventNotify = endEvent
  .lOffset = DSBPN_OFFSETSTOP
End With
gDSB.SetNotificationPositions 1, dsbpn()

ループしない条件でバッファの終了位置に到達したか、アプリケーションが DirectSoundSecondaryBuffer8.Stop メソッドを呼び出したか、どちらかの理由でバッファが再生を停止したとき、通知のオフセットは DSBPN_OFFSETSTOP または -1 という、イベントが設定されることを示す特別な値を取る。これが発生すると、アプリケーション定義のコールバック関数が自動的に呼び出され、パラメータとして endEvent イベント識別子が渡される。

Private Sub DirectXEvent8_DXCallback(ByVal eventid As Long)
  If eventid = endEvent Then
    lblStatus.Caption = "Buffer stopped."
  End If
End Sub


サウンドのミキシング

DirectSound で複数のストリームをミキシングするのは簡単である。単純にセカンダリ サウンド バッファを作成し、各サウンドに対する DirectSoundSecondaryBuffer8 オブジェクトを取得するだけである。次にそれらのバッファを同時に再生する。DirectSound はプライマリ サウンド バッファでのミキシングを処理し、その結果を再生する。

アプリケーション内のすべてのサウンドが同じウェーブ フォーマットを使用し、ハードウェア出力フォーマットがそれらのサウンドのフォーマットと一致している場合、DirectSound ミキサは最高の品質のサウンドをもたらす。この場合、ミキサはフォーマット変換をする必要がない。

ハードウェア出力フォーマットを変更するには、プライマリ サウンド バッファを作成し、DirectSoundPrimaryBuffer8.SetFormat メソッドを呼び出す。SetFormat メソッドを呼び出すために、DSSCL_PRIORITY またはそれ以上の協調レベルを設定する必要がある。アプリケーションが入力フォーカスを取得するたびに、DirectSound はハードウェア フォーマットを、前回の呼び出しで指定されたフォーマットに復元する。

セカンダリ バッファを作成する前に、プライマリ バッファのフォーマットを設定しなければならない。

注 WDM ドライバを使う場合は、プライマリ バッファのフォーマットを設定しても効果がない。フォーマットはカーネル ミキサによって決定される。詳細については、「DirectSound ドライバ モデル」を参照すること。


バッファ管理

DirectSoundPrimaryBuffer8.GetCaps と DirectSoundSecondaryBuffer8.GetCaps の各メソッドは、バッファの能力を取得する。

アプリケーションは DirectSoundPrimaryBuffer8.GetStatus または DirectSoundSecondaryBuffer8.GetStatus メソッドを使って、現在のサウンド バッファが再生中か停止しているかを確認できる。

DirectSoundPrimaryBuffer8.GetFormat または DirectSoundSecondaryBuffer8.GetFormat メソッドを使うと、バッファ内のサウンド データのフォーマット情報を取得できる。DirectSoundPrimaryBuffer8.SetFormat メソッドを使って、プライマリ バッファ内のサウンド データのフォーマットを取得および設定することもできる。

注 DirectSoundSecondaryBuffer8 用の SetFormat メソッドはない。セカンダリ バッファが作成された後、そのフォーマットが固定される。ほかのフォーマットを使うセカンダリ バッファが必要な場合は、そのフォーマットを指定して新しいサウンド バッファを作成しなければならない。

サウンド バッファ用のメモリは特定の状況で失われることがある。たとえば、バッファがサウンド カードのメモリに置かれていて、ほかのアプリケーションがハードウェア リソースの制御を取得した場合である。書き込み優先の協調レベルで動作するアプリケーションがフォアグラウンドに移動した場合も、メモリが失われることがある。この場合、ほかのすべてのサウンド バッファは失われるので、フォアグラウンドに移動したアプリケーションはプライマリ バッファに直接書き込める。

失われたバッファに対して DirectSoundSecondaryBuffer8.WriteBuffer または DirectSoundSecondaryBuffer8.Play メソッドを呼び出すと、DSERR_BUFFERLOST エラー コードが返される。バッファを失わせたアプリケーションの協調レベルが書き込み優先から下がったり、そのアプリケーションがバックグラウンドに移動した場合は、ほかのアプリケーションは DirectSoundSecondaryBuffer8.Restore メソッドを呼び出してバッファ メモリの再配置を試みることができる。成功した場合、このメソッドはバッファ メモリと、ボリュームやパンの設定などほかのすべての設定を復元する。しかし、復元されたバッファは有効なサウンド データを保持していない。したがって、アプリケーションは復元されたバッファにデータをもう一度書き込むべきである。


ウェーブ データの使い方

DirectSound バッファは、固定サンプリング レートのサウンドのデジタル サンプルで構成されるウェーブフォーム オーディオ データのみ再生する。アナログ シグナルを数字のシーケンスで表現することを、パルス コード変調 (PCM) と呼ぶ。

ウェーブ データは、通常、RIFF (Resource Interchange File Format) のファイルまたはリソースに保存される。このデータには、サンプリング レートや出力チャンネル数などのパラメータを含む、ウェーブ フォーマットの記述が含まれる。

サウンドの特定のフォーマットは、WAVEFORMATEX 型を使って記述できる。

注 DirectX for Visual Basic タイプ ライブラリの WAVEFORMATEX 型は、Mmreg.h で宣言され、ウェーブ ファイルやリソースのフォーマット チャンクで使用される WAVEFORMATEX 構造体と同じではない。フォーマット チャンクの読み込みおよび DirectX WAVEFORMATEX 型への関連データのコピーの方法については、「ウェーブ ファイルの読み込み」を参照すること。

DirectSound8.CreateSoundBufferFromFile または DirectSound8.CreateSoundBufferFromResource を使ってスタティック バッファを作成する場合、作成されるバッファのフォーマットは常にデータのフォーマットに一致するので、バッファのフォーマットは指定しない。ただし、DirectSound8.CreateSoundBuffer を使ってバッファを作成する場合はフォーマットを指定する必要があり、このフォーマットはバッファで再生するデータのフォーマットと一致していなければならない。

DirectSound は、圧縮ウェーブ フォーマットをサポートしていない。アプリケーションはサウンド バッファにデータを書き込む前に、Platform SDK 内の Win32 API で提供されているオーディオ圧縮マネージャ (ACM) 関数を使って、圧縮されたオーディオ データを PCM フォーマットに変換すべきである。この代わりに、DirectMusic パフォーマンスで再生するために圧縮されたウェーブをロードしたときに、自動的に ACM を利用する DirectMusic ローダーを使用することもできる。

ウェーブの詳細については、次のトピックを参照すること。

  • マルチチャンネル ウェーブ フォーマット
  • ウェーブ ファイルの読み込み
  • リソースからのウェーブ データの読み込み


マルチチャンネル ウェーブ フォーマット

ここでは、C++ でのアプリケーション開発について説明する。DirectX for Visual Basic では、複数のチャンネルを持つウェーブ フォーマットはサポートされない。


ウェーブ ファイルの読み込み

ここでは、DirectMusic ローダーおよびパフォーマンスを使用せずに、ウェーブ ファイルのデータを DirectSound バッファにロードする方法について説明する。ほとんどのアプリケーションでは、ウェーブ データやバッファを直接処理する必要はない。ウェーブのロードや再生の優先される方法については、「オーディオ データのロード」および「サウンドの再生」を参照すること。

短いサウンドの場合、DirectSound だけを使ってウェーブ ファイルを再生する最も簡単な方法は、DirectSound8.CreateSoundBufferFromFile メソッドを呼び出してスタティック バッファにロードする方法である。「セカンダリ バッファの作成」を参照すること。

メモリに収まらない大きいファイルの場合は、ストリーム バッファを作成して、ファイルを分割して読み込む必要がある。

ウェーブ ファイルは RIFF (Resource Interchange File Format、リソース交換ファイル フォーマット) を採用しており、ファイル ヘッダーと、それぞれヘッダーとデータから成る任意の数の "チャンク" によって構成されている。チャンク ヘッダーは、データの型を識別する 4 文字のタグとデータの長さを与える Long で構成される。

ウェーブ ファイル ヘッダーは次のようになる。

  • 文字列 "RIFF"。Long &H46464952 としても読み取り可能。
  • ファイルのサイズを与える Long。
  • 文字列 "WAVE"。Long &H45564157 としても読み取り可能。

最初のチャンクは常にフォーマット チャンクであり、次のようになる。

  • 文字列 "fmt" とそれに続くスペース。
  • フォーマット データのサイズを与える Long。
  • データのウェーブ フォーマットを記述するデータ。PCM フォーマットのファイルでは、このデータは WAVEFORMATEX 型のデータと同じ 16 バイトのデータとなる。

ウェーブ ファイルの PCM サンプル データは、文字列 "data" で始まるチャンクに保持される。これは、Long &H61746164 としても読み取られる。ほとんどの場合このチャンクはフォーマット チャンクに直接続くが、RIFF が拡張可能なフォーマットなので、ほかのタイプのチャンクが先行しないという保証はない。ファイル パーサーには、処理できないチャンクを無視できる能力が必要である。

ウェーブ ファイルを解析するには、3 つのユーザー定義型を準備するとよい。最初のタイプは、ファイル ヘッダーとフォーマット チャンクのヘッダー内の情報をすべて受け取る。

Private Type FileHeader
    lRiff As Long
    lFileSize As Long
    lWave As Long
    lFormat As Long
    lFormatLength As Long
End Type

2 番目のタイプは、フォーマット データを受け取る。これには、メンバが異なる順序である WAVEFORMATEX 型は使用できない。このユーザー定義型は、16 バイトのチャンクのうち 14 バイトだけを取得しなければならない。なぜなら、チャンク内の最後の Integer 値は WAVEFORMATEX.lExtra と同等で、標準的な PCM ファイルでは常に 0 だからである。

Private Type WaveFormat
    wFormatTag As Integer
    nChannels As Integer
    nSamplesPerSec As Long
    nAvgBytesPerSec As Long
    nBlockAlign As Integer
    wBitsPerSample As Integer
End Type

3 番目のタイプは、データ チャンクも含め任意のチャンクのヘッダーを取得するために使われる。

Private Type ChunkHeader
    lType As Long
    lLen As Long
End Type

次のサンプル関数は、ファイルが RIFF ウェーブ ファイルであることを確認し、サンプル データの始まりを検索し、ウェーブ フォーマットについての情報を保持する WAVEFORMATEX 型を返す。

Dim FileFree As Long           ' グローバル ファイルのハンドル。
Dim lDataLength As Long        ' グローバル データの長さ。

Private Function FillFormat(FileName As String) As WAVEFORMATEX

    Dim Header As FileHeader
    Dim HdrFormat As WaveFormat
    Dim chunk As ChunkHeader
    Dim by As Byte
    Dim i As Long

    ' ファイルを開き、ヘッダーを読み込む。

    Close #FileFree
    FileFree = FreeFile
    Open FileName For Binary Access Read As #FileFree
    Get #FileFree, , Header

    ' "RIFF" タグをチェックし、見つからない場合は終了する。

    If Header.lRiff <> &H46464952 Then
        Exit Function
    End If

    ' "wAVE" タグをチェックし、見つからない場合は終了する。

    If Header.lWave <> &H45564157 Then
        Exit Function
    End If

    ' フォーマット チャンクの長さをチェックし、16 未満の場合は、
    ' PCM データではないので、使用できない。

    If Header.lFormatLength < 16 Then
        Exit Function
    End If

    ' フォーマットを取得する。

    Get #FileFree, , HdrFormat

    ' フォーマット バイトを破棄して次のチャンクを検索する。

    For i = 1 To Header.lFormatLength - 16
        Get #FileFree, , by
    Next

    ' "data" チャンクに到達するまでチャンクを無視する。

    Get #FileFree, , chunk
    Do While chunk.lType <> &H61746164
        For i = 1 To chunk.lLen
            Get #FileFree, , by
        Next
        Get #FileFree, , chunk
    Loop

    ' データのサイズを取得する。

    lDataLength = chunk.lLen

   ' 返された型にフォーマット情報を書き込む。

    With FillFormat
        .lAvgBytesPerSec = HdrFormat.nAvgBytesPerSec
        .lExtra = 0
        .lSamplesPerSec = HdrFormat.nSamplesPerSec
        .nBitsPerSample = HdrFormat.wBitsPerSample
        .nBlockAlign = HdrFormat.nBlockAlign
        .nChannels = HdrFormat.nChannels
        .nFormatTag = HdrFormat.wFormatTag
    End With

End Function

これでアプリケーションは、ファイルからのデータを読み込み、セカンダリ サウンド バッファにそのデータをストリーミングできるようになる。ファイルから直接データをセカンダリ バッファに読み込むことはできない。まず、データをプライベート バッファに読み込んだ後、DirectSoundSecondaryBuffer8.WriteBuffer を使ってセカンダリ バッファにコピーする。

ストリーミングの詳細については、「ストリーム バッファの使い方」および「再生バッファの通知」を参照すること。


リソースからのウェーブ データの読み込み

リソースとして格納されたサウンドは短いことが多いので、スタティック バッファで再生されることが望ましい。スタティック バッファを作成してリソースからデータを書き込むには、DirectSound8.CreateSoundBufferFromResource メソッドを使う。例については、「スタティック バッファの書き込みと再生」を参照すること。

さらに長いサウンドはウェーブ ファイルに格納され、ストリーム バッファから再生される。詳細については、次のトピックを参照すること。

  • ストリーム バッファの使い方
  • ウェーブ ファイルの読み込み


DirectSound でのエフェクトの使い方

純粋な DirectSound アプリケーションでのエフェクトの再生は、基本的には DirectMusic のパフォーマンスおよびオーディオパスを使用するアプリケーションの場合と同様に処理される。詳細については、「エフェクトの使い方」を参照すること。DirectSound アプリケーションにはオーディオパスがないので、常にバッファを直接操作する。

バッファがあまり小さいと、エフェクトがうまく動作しない。DirectSound では、DSBSIZE_FX_MIN ミリ秒以下のデータしか保持できないエフェクト使用可能なバッファは作成できない。

DSBUFFERDESC 型の DSBCAPS_CTRLFX フラグを設定して、DMO を保持できるセカンダリ バッファを作成する。

セカンダリ サウンド バッファでエフェクトを実装するには、DirectSoundSecondaryBuffer8.SetFX を使う。

エフェクトのオブジェクトを取得するには、DirectSoundSecondaryBuffer8.GetObjectInPath を使う。このメソッドは、DirectMusicAudioPath8.GetObjectInPath とは異なり、lStage パラメータを取らない。これは、バッファから取得できるオブジェクトは DMO だけだからである。


サウンド キャプチャ

ここでは、DirectMusic および DirectSoundCapture オブジェクトを使ったサウンドのキャプチャについて説明する。説明するトピックは、次のとおりである。

  • MIDI のキャプチャ
  • ウェーブのキャプチャ

注 DirectX for Visual Basic では、MIDI のキャプチャはサポートされない。


MIDI のキャプチャ

ここでは、C++ でのアプリケーション開発について説明する。DirectX for Visual Basic では、MIDI のキャプチャはサポートされない。


ウェーブのキャプチャ

DirectSoundCapture8 オブジェクトは、サウンド キャプチャ デバイスの能力の問い合わせや、入力ソースからオーディオをキャプチャするためのバッファの作成に使われる。DirectSoundCapture8 を使うと、PCM フォーマットまたは圧縮フォーマットでデータをキャプチャできる。

DirectSoundCaptureBuffer8 オブジェクトは、入力デバイスからのデータを受け取るためのバッファを表す。再生バッファと同様、このバッファは循環という概念を採用している。入力ポインタがバッファの最後に到達すると、自動的に開始点に戻る。

DirectSoundCaptureBuffer8 オブジェクトのメソッドを使うと、バッファのプロパティの取得、オーディオ キャプチャの開始と停止、メモリの一部のロックができるので、ファイルに保存するなどの目的でデータを安全に取得できる。

ウェーブのキャプチャの詳細については、次のトピックを参照すること。

  • キャプチャ デバイスの列挙
  • DirectSoundCapture オブジェクトの作成
  • キャプチャ デバイスの能力
  • キャプチャ バッファの作成
  • キャプチャ バッファの情報
  • キャプチャ バッファの通知
  • キャプチャ バッファのエフェクト
  • キャプチャ バッファの使い方
  • ウェーブ ファイルへの書き込み


キャプチャ デバイスの列挙

ユーザーが優先するキャプチャ デバイスでサウンドをキャプチャするだけのアプリケーションでは、利用可能なデバイスを列挙する必要はない。vbNullString または定義済みの GUID を DirectX8.DirectSoundCaptureCreate に渡すことによって、デフォルトのデバイスを作成できる。詳細については、「DirectSoundCapture オブジェクトの作成」を参照すること。

特定の種類のデバイスを探している場合や、複数のデバイスを使って動作する必要がある場合は、システム上で利用可能なデバイスを列挙しなければならない。

列挙は 3 つの目的で使われる。

  • 利用可能なハードウェアを報告。
  • 各デバイスに GUID を供給。
  • 各デバイスを列挙したときに、各デバイスを初期化。その結果、各デバイスの能力をチェックできる。

デバイスを列挙するには、DirectX8.GetDSCaptureEnum メソッドを最初に呼び出し、デバイスのコレクションを表す DirectSoundEnum8 オブジェクトを作成しなければならない。その後、DirectSoundEnum8.GetDescription、DirectSoundEnum8.GetGuid、DirectSoundEnum8.GetName の各メソッドを使って各デバイスについて問い合わせできる。

DirectSoundEnum8 の使用例については、「サウンド デバイスの列挙」を参照すること。


DirectSoundCapture オブジェクトの作成

DirectSoundCapture8 オブジェクトを作成するには、DirectX8.DirectSoundCaptureCreate メソッドを呼び出す。

DirectSoundCaptureCreate に対する guid パラメータには、列挙によって取得される GUID、または次のいずれかの値を指定できる。

DSDEVID_DefaultCapture
デフォルトのシステム キャプチャ デバイス。デバイスの GUID パラメータで vbNullString を渡すことによって、このデバイスを指定することもできる。
DSDEVID_DefaultVoiceCapture
デフォルトの音声通信キャプチャ デバイス。これは、通常、USB マイク付きヘッドセットなどのセカンダリ デバイスである。

デバイス ドライバが存在しない場合は、この呼び出しはエラーを発生させる。

DirectSound8 オブジェクトと DirectSoundCapture8 オブジェクトを共存させたい場合は、DirectSoundCapture8 オブジェクトを作成する前に DirectSound8 オブジェクトを作成する。

オーディオ機器によっては、デフォルトで全二重オーディオ構成になっていないものもある。DirectSound8 オブジェクトと DirectSoundCapture8 オブジェクトを作成する際に問題が発生した場合は、ユーザーに対してオーディオ デバイス プロパティのチェックと、全二重オーディオが有効になっていることの確認を求めなければならない。


キャプチャ デバイスの能力

キャプチャ デバイスの能力を取得するには、DirectSoundCapture8.GetCaps メソッドを呼び出す。このメソッドのパラメータは、DSCCAPS 型である。戻り値として、この型はこのデバイスがサポートするチャンネル数、およびサポートされるフォーマットに関する値の組み合わせを保持する。

非 WDM ドライバでは、キャプチャ デバイスは一度に 1 つのアプリケーションでのみ使用できる。ドライバが、複数のアプリケーションによるデバイスの同時使用をサポートしている場合は、DSCCAPS の dwFlags メンバに DSCCAPS_MULTIPLECAPTURE が返される。各アプリケーションは、キャプチャ バッファについてそれぞれのフォーマットを設定できる。


キャプチャ バッファの作成

キャプチャ バッファを作成するには、DirectSoundCapture8.CreateCaptureBuffer メソッドを呼び出す。

このメソッドに渡されるパラメータの 1 つは DSCBUFFERDESC 構造体であり、これは目的のバッファの特性を記述している。fxFormat メンバは WAVEFORMATEX 型であるが、目的のウェーブ フォーマットの詳細に従ってこの型を初期化しなければならない。

アプリケーションが DirectSound8 と DirectSoundCapture8 の両方を使う場合、キャプチャ バッファのフォーマットがプライマリ バッファのフォーマットと異なっていると、キャプチャ バッファの作成は失敗する。一部のカードはクロックを 1 つしか用意していないため、2 つの異なった周波数でキャプチャと再生を行えないのが原因である。

次の例では、およそ 1 秒分のデータを保持するキャプチャ バッファを設定する。

' dsc は DirectSoundCapture8 オブジェクトである。

Dim dscbd As DSCBUFFERDESC
Dim dscb As DirectSoundCaptureBuffer8

' ウェーブ フォーマットを設定する。
With dscbd.fxFormat
    .nFormatTag = WAVE_FORMAT_PCM
    .nChannels = 2
    .lSamplesPerSec = 22050
    .nBitsPerSample = 16
    .nBlockAlign = _
    .nBitsPerSample / 8 * WaveFormat.nChannels
    .lAvgBytesPerSec = _
            waveFormat.lSamplesPerSec * waveFormat.nBlockAlign
    .nSize = 0    ' WAVE_FORMAT_PCM の場合は無視される。
End With

dscbd.lFlags = DSCBCAPS_DEFAULT
dscbd.lBufferBytes = dscbd.fxFormat.lAvgBytesPerSec

Set dscb = dsc.CreateCaptureBuffer (dscbd)


キャプチャ バッファの情報

DirectSoundCaptureBuffer8.GetCaps メソッドを使って、バッファ能力についての情報を取得する。バッファ作成時に設定されたバッファのデータ形式についての情報を取得するには、DirectSoundCaptureBuffer8.GetFormat メソッドを呼び出す。

キャプチャ バッファが現在行っていることを把握するには、DirectSoundCaptureBuffer8.GetStatus メソッドを呼び出す。このメソッドはフラグの組み合わせを返すが、そのフラグはバッファがキャプチャリングでビジーであるかどうか、ビジーの場合はループしているかどうか (つまり DirectSoundCaptureBuffer8.Start を直前に呼び出した時点で DSCBSTART_LOOPING フラグを設定していたか) を示す。

最後に、DirectSoundCaptureBuffer8.GetCurrentPosition メソッドは、バッファ内での現在の読み込みカーソルとキャプチャ カーソルのオフセットを返す。読み込みカーソルは、この時点で完全にキャプチャされてバッファに置かれたデータの最後である。キャプチャ カーソルは、現在ハードウェアからコピーされている最中のデータ ブロックの最後である。バッファから安全にコピーできるのは読み込みカーソルまでのデータのみである。


キャプチャ バッファの通知

読み込みカーソルがバッファ内のある位置または最後に達したときに、アプリケーションへの通知を発生させたいことがある。バッファ内での読み込みカーソルまでの部分は、安全にデータを読み込むことができる。DirectSoundCaptureBuffer8.SetNotificationPositions メソッドを使うと、イベントのシグナルを送信するポイントをバッファ内にいくつでも設定できる。

バッファに通知イベントを設定するには、バッファのコードを保持するフォームに DirectXEvent8 クラスを最初に実装しなければならない。ドロップダウン クラス リストから DirectXEvent8 を選択して DirectXEvent8.DXCallback メソッドを作成し、イベントが通知されたときに実行するコードを追加する。

DirectX8.CreateEvent メソッドを呼び出してイベント ハンドルを作成し、そのイベントハンドルを DSBPOSITIONNOTIFY 型の hEventNotify メンバに渡す。この型を DirectSoundCaptureBuffer8.SetNotificationPositions メソッドに渡す。これで、再生カーソルが特定の位置に到達するたびに、イベント ハンドルが DirectXEvent8.DXCallback に渡される。


キャプチャ バッファのエフェクト

ここでは、C++ でのアプリケーション開発について説明する。DirectX for Visual Basic では、キャプチャ バッファのエフェクトはサポートされない。


キャプチャ バッファの使い方

サウンドのキャプチャは、次のステップで構成される。

  1. DirectSoundCaptureBuffer8.Start メソッドを呼び出してバッファリングを開始する。入力デバイスから得たオーディオ データを、バッファの開始位置以降に書き込む。
  2. 希望の量のデータが利用可能になるまで待つ。キャプチャ カーソルが特定の地点に達する時期を決定する方法の 1 つについては、「キャプチャ バッファの通知」を参照すること。
  3. 十分なデータが利用可能になったとき、DirectSoundCaptureBuffer8.ReadBuffer メソッドを呼び出してキャプチャ バッファの一部を読み込む。

    読み込みを試みる部分が、キャプチャに使われようとしているメモリ部分と重なっていないことを確認するには、最初に DirectSoundCaptureBuffer8.GetCurrentPosition を呼び出して現在の読み込みカーソルの位置を取得する。読み込みカーソルについては、「キャプチャ バッファの情報」を参照すること。

  4. 全データのキャプチャが終わるまで、ステップ 2 から 3 を繰り返す。次に、DirectSoundCaptureBuffer8.Stop メソッドを呼び出す。

デフォルトでは、キャプチャ カーソルがバッファの最後に達すると、バッファはキャプチャリングを自動的に停止する。しかし、DirectSoundCaptureBuffer8.Start メソッドに渡す flags パラメータで DSCBSTART_LOOPING フラグを設定した場合は、アプリケーションが DirectSoundCaptureBuffer8.Stop メソッドを呼び出すまでキャプチャは続行される。

キャプチャ カーソルが通知位置に達するたびに、DirectXEvent8 を実装するフォームで次のプロシージャが呼び出される。このプロシージャは、利用可能な新しいデータの量を計算し、中間バッファにコピーしてからファイルに書き込む。

Private Sub DirectXEvent8_DXCallback(ByVal eventid As Long)

' 次のグローバル変数を使用する。
' lastPos As Long - キャプチャが開始されるたびに 0 に初期化される。
' BytesWritten As Long – これも 0 に初期化される。
' dscb As DirectSoundCaptureBuffer8
' dscbDesc As DSCBUFFERDESC
' EventStop As Long

  Static curPos As Long
  Static curs As DSCURSORS
  Dim dataBuf() As Byte
  Dim dataSize As Long

  dscb.GetCurrentPosition curs
  curPos = curs.lWrite  ' Position up to which data is valid

  ' 一時的な中間データ バッファを作成する。
  ' lastPos は Long のグローバル変数であり、キャプチャが開始されるたびに
  ' 0 に初期化される。

  dataSize = curPos - lastPos
  If dataSize < 0 Then         ' curPos wrapped around.
    dataSize = dscbDesc.lBufferBytes - lastPos + curPos
  End If

  ReDim dataBuf(dataSize - 1)
  dscb.ReadBuffer lastPos, dataSize, dataBuf(0), DSCBLOCK_DEFAULT

  Put #1, , dataBuf
  BytesWritten = BytesWritten + dataSize
  lastPos = curPos

  If (eventid = EventStop) Then
    CloseFile
  End If

End Sub

通知位置が設定されたときに、EventStop イベントはオフセット DSBPN_OFFSETSTOP に関連付けられている。このイベントはキャプチャ バッファの停止時に通知される。この通知に対して、アプリケーションは、ファイル ヘッダーに情報を追加してファイルを閉じるプロシージャを呼び出す。ウェーブ ファイルにファイル ヘッダーを書き込む方法については、「ウェーブ ファイルへの書き込み」を参照すること。


ウェーブ ファイルへの書き込み

短いサウンドは、DirectSoundSecondaryBuffer8.SaveToFile を使って、セカンダリ バッファからウェーブ ファイルに保存できる。このメソッドは、バッファの内容全体をファイルにコピーする。

多くの場合、サウンドの保存はキャプチャ バッファから始める。次のコードは、キャプチャ バッファ dscb からセカンダリ バッファに、次にファイルにデータを移動する方法を示している。

Dim ds As DirectSound8
Dim dscb As DirectSoundCaptureBuffer8
Dim dscd As DSCBUFFERDESC
Dim dsd As DSBUFFERDESC
Dim capCurs As DSCURSORS
Dim numBytes As Long
Dim ByteBuffer() As Integer
.
.
.
' ds が作成され、dscb が作成されてデータを格納し、
' dscd がキャプチャ バッファのフォーマットを保持しているとする。

' 同じフォーマットで、キャプチャ バッファに書き込まれた
' すべてのデータを格納するのに十分な大きさのセカンダリ バッファを作成する。

dscb.GetCurrentPosition capCurs
numBytes = capCurs.lWrite + 1
dsd.lBufferBytes = numBytes
dsd.fxFormat = dscd.fxFormat
Set dsb = ds.CreateSoundBuffer(dsd)

' 同じデータを保持するのに十分な大きさのプライベート バッファを作成する。

ReDim ByteBuffer(numBytes)

' キャプチャ バッファの内容をプライベート バッファに読み込む。

dscb.ReadBuffer 0, numBytes, ByteBuffer(0), DSCBLOCK_DEFAULT

' プライベート バッファをセカンダリ バッファに書き込む。

dsb.WriteBuffer 0, numBytes, ByteBuffer(0), DSBLOCK_DEFAULT

' ウェーブを保存する。

dsb.SaveToFile "captured.wav"

キャプチャ バッファの長さを超えてしまうサウンドに対しては、開発者自身がウェーブ ファイルを作成し、そのファイルにデータをストリーミングしなければならない。キャプチャされたデータをウェーブ ファイルにストリーミングするのは、次のステップで行う。

  1. ファイルを作成し、ファイル ヘッダー、フォーマット チャンク、およびデータ チャンクのヘッダーを書き込む。フォーマット チャンクは、キャプチャ バッファのフォーマットを記述しなければならない。ただし、フォーマットの要素は WAVEFORMATEX 型と同じ順番ではないことに注意すること。ヘッダーとチャンクの編成の情報については、「ウェーブ ファイルの読み込み」を参照すること。
  2. キャプチャ バッファからプライベート バッファまで、またそのバッファからファイルまでのデータのストリーミングを行う。このとき、書き込まれたバイトの数を追跡する。詳細については、「キャプチャ バッファの使い方」を参照すること。
  3. キャプチャが停止し、すべてのデータが書き込まれたら、データ チャンクの長さとファイルの合計サイズを計算し、これらの値をデータ チャンク ヘッダーとファイル ヘッダーのそれぞれの適切な位置に書き込む。

次のコードは、ファイルを作成して RIFF ヘッダー情報を書き込む。

Private Type FileHeader
    lRiff As Long
    lFileSize As Long
    lWave As Long
    lFormat As Long
    lFormatLength As Long
End Type

Private Type WaveFormat
    wFormatTag As Integer
    nChannels As Integer
    nSamplesPerSec As Long
    nAvgBytesPerSec As Long
    nBlockAlign As Integer
    wBitsPerSample As Integer
' Integer 型の cbSize
End Type

Private Type ChunkHeader
    lType As Long
    lLen As Long
End Type

Dim fh As FileHeader
Dim wf As WaveFormat
Dim ch As ChunkHeader

Private Sub OpenFile(WaveFileName As String)

  Open WaveFileName For Binary Access Write As #1

  With fh
    .lRiff = &H46464952    ' <RIFF> チャンク タグ
    .lFileSize = 0         ' 後で取得
    .lWave = &H45564157    ' <WAVE> チャンク タグ
    .lFormat = &H20746D66  ' <fmt > チャンク タグ
    .lFormatLength = Len(wf)
  End With

  Put #1, , fh

  With wf
    .wFormatTag = dscbDesc.fxFormat.nFormatTag
    .nChannels = dscbDesc.fxFormat.nChannels
    .nSamplesPerSec = dscbDesc.fxFormat.lSamplesPerSec
    .wBitsPerSample = dscbDesc.fxFormat.nBitsPerSample
    .nBlockAlign = dscbDesc.fxFormat.nBlockAlign
    .nAvgBytesPerSec = dscbDesc.fxFormat.lAvgBytesPerSec
  End With

  Put #1, , wf

    ch.lType = &H61746164  ' <data> チャンク タグ

  Put #1, , ch

End Sub

これで、キャプチャしたデータをファイルに追加できるようになった。ファイルに書き込まれたデータのバイト数が BytesWritten と呼ばれる Long に格納されているとすると、ファイルは次のプロシージャを使って閉じられる。

Private Sub CloseFile()

  Dim fsize As Long

  ' ファイルのサイズを書き込む。

  fsize = Len(fh) + Len(wf) + Len(ch) + BytesWritten
  Put #1, 5, fsize

  ' データのチャンク ヘッダーをサイズに書き換える。

  ch.lLen = BytesWritten
  Put #1, Len(fh) + Len(wf) + 1, ch

  Close #1

End Sub


DirectX Audio の高度なトピック

ここでは、「DirectX Audio の使い方」で記述されている機能よりも高度な機能を必要とする特殊なアプリケーションについて説明する。

説明するトピックは、次のとおりである。

  • DirectMusic トラック
  • DirectMusic メッセージの使い方
  • DirectMusic ポートの使い方
  • カスタム ロード
  • 音色コレクションの使い方
  • 下位レベル DLS
  • DirectMusic ツール
  • プロパティ セット
  • DirectSound の性能の最適化
  • プライマリ バッファへの書き込み

Microsoft® DirectX® for Visual Basic タイプ ライブラリでは C++ API のより高度な機能をサポートしていない部分があるため、ここで説明するトピックの多くは、Microsoft® Visual Basic® での開発とは関係がない。ただし、DirectX のヘルプでは、C++ と Visual Basic の説明が共通のソースに基づいているため、これらのトピックも目次に表示される。


DirectMusic トラック

ここでは、C++ でのアプリケーション開発について説明する。DirectX for Visual Basic では、個々のトラックにアクセスできるアプリケーションは提供されない。


標準トラックの種類

ここでは、C++ でのアプリケーション開発について説明する。DirectX for Visual Basic では、個々のトラックにアクセスできるアプリケーションは提供されない。


トラック構成

ここでは、C++ でのアプリケーション開発について説明する。DirectX for Visual Basic では、個々のトラックにアクセスできるアプリケーションは提供されない。


DirectMusic メッセージの使い方

サウンド データは、メッセージの形で DirectMusic パフォーマンスに渡される。ほとんどの場合、メッセージの作成および処理は自動的に行われ、アプリケーションで直接これらの処理をする必要はない。ただし、メッセージの基本的な知識は DirectMusic のしくみを理解するのに役立ち、理解が深まるほど、メッセージを使ってパフォーマンスを細かく制御できるようになる。

DirectMusic では、2 種類のメッセージが使用される。

  • パフォーマンス メッセージ。シーケンス化されたデータはすべて、この形式でパフォーマンス エンジンに渡される。これらのメッセージには、データのタイミングおよびルーティングに関する詳細な情報が含まれている。
  • スタンダード MIDI メッセージ。これらのメッセージは、MIDI ファイルまたはデバイスから読み込まれ、ほかのデバイスに直接渡される (スルーされる) か、再生時にパフォーマンスによってパフォーマンス メッセージ形式に変換される。

アプリケーションは、MIDI メッセージを直接処理しない。セグメントを演奏する場合、そのすべてのデータはパフォーマンス メッセージ形式であり、最終的な出力ツールに渡されるまでその形式のままである。最終的な出力ツールでは、パフォーマンス メッセージを MIDI メッセージ フォーマットに変換した後、シーケンス化してシンセサイザに渡す。ただし、一部のパフォーマンス メッセージには、スタンダード MIDI メッセージと同様の情報が含まれている。このようなメッセージを理解するために、ここでは MIDI メッセージ フォーマットのいくつかの点について説明する。

注 DirectMusicPerformance8.SendMIDIPMSG メソッドは、スタンダード MIDI メッセージのデータに相当するデータを送信する。ただし、データはパフォーマンス メッセージの形式である。

ほとんどのパフォーマンス メッセージは、セグメントが演奏されるときに、セグメントのトラックによって送信される。アプリケーションは、メッセージを送信して、MIDI コントローラの設定、単一のノートの演奏、テンポの変更などの処理も行うことができる。

メッセージを送信した後、アプリケーションはメッセージを取得または変更できない。たとえば、DirectMusic Producer でオーサリングしたセグメントには、テキスト メッセージを生成する歌詞トラックが含まれる場合がある。DirectX for Visual Basic では、アプリケーションはこれらのメッセージを取得して歌詞を表示することはできない。

通知は、アプリケーションではメッセージを取得できないという規則の例外である。DirectMusicPerformance8.GetNotificationPMsg メソッドによって、アプリケーションは DMUS_NOTIFICATION_PMSG メッセージを取得できる。詳細については、「通知とイベントの処理」を参照すること。

次のトピックでは、メッセージとそのルーティング方法について説明する。

  • チャンネル
  • メッセージの作成と配信
  • アプリケーションで作成されたメッセージ
  • パフォーマンス メッセージのタイプ
  • カーブ
  • MIDI メッセージ


チャンネル

チャンネルは、パフォーマンス内の 1 つのパートに固有のメッセージの送信先である。たとえばチャンネルは、音色にサウンドを発生させるノートオン メッセージを受け取ったり、パートに別の音色を割り当てるプログラム チェンジ メッセージを受け取る。「MIDI チャンネル メッセージ」を参照すること。

MIDI 1.0 規格では、16 個の MIDI チャンネルがあり、一度に 16 を超える音色は演奏できないことを意味している。DirectMusic では、この規格に対応すると同時に、アプリケーションがより多くのチャンネルを同時に利用できるように、チャンネル グループが作成される。最大 65,536 個のチャンネル グループが同時に存在し、それぞれに 16 個のチャンネルが含まれるので、チャンネル総数は 100 万以上に上る。特定のポートに、そのポートがサポートする範囲で任意の数のチャンネル グループを割り当てることができる。MIDI ハードウェア ポートには、1 つのチャンネル グループしか割り当てることができない。

システム エクスクルーシブ メッセージは、1 つのチャンネル グループ内の 16 チャンネルのすべてに対して送信できるが、ほかのチャンネル グループ宛てには送信できない。

DirectMusic パフォーマンス内のすべてのパートは、固有のパフォーマンス チャンネル、つまり P チャンネルを持つ。パフォーマンス チャンネルは、特定のポートに対する特定のグループ内の特定の MIDI チャンネルを表す。パフォーマンスがあるバンドを選択すると、そのバンド内の各音色は 1 つのパフォーマンス チャンネルにマップされ、そのチャンネルのパートはその音色で演奏される。

オーディオパスが使用されている場合は、異なるオーディオパス上の同一のパフォーマンス チャンネルが異なる出力チャンネルにマップされる。

チャンネルの優先順位

同時に演奏できるノートの数は、ポートで利用できるボイス数によって制限される。ボイスは、チャンネルで演奏される 1 つのノートまたはウェーブを合成する、リソースのセットである。利用できるボイスの数より多くのノートが演奏される場合は、シンセサイザによって、1 つまたは複数のノートが抑制されなければならない。どのノートを演奏するかは、現在ノートを演奏しているボイスの優先順位によって決定され、これはチャンネルの優先順位に基づく。デフォルトでは、チャンネルはインデックス値に基づいて順位付けされる。ただし、チャンネル 10 は MIDI パーカッション チャンネルで、優先順位は最も高くなる。


メッセージの作成と配信

セグメントが演奏されている場合、ほとんどのトラックは、再生中に発生するイベントに関する情報を含むメッセージを生成する。詳細については、「DirectMusic トラック」を参照すること。

数種類のメッセージを送信するトラックもある。たとえば、スタイル トラックはノート メッセージと拍子記号メッセージを送信する。これらの場合、アプリケーションはトラックの特定の種類のメッセージを無効にすることができる。詳細については、「トラック パラメータの無効化と有効化」を参照すること。

パフォーマンス エンジンは、各メッセージをクロック タイムでいつ処理するかを決定する。チャンネル メッセージの場合、パフォーマンスはメッセージを取得するパフォーマンス チャンネルも決定する。この情報は、メッセージ タイプ、ソース トラック、メッセージを受信する最初のツールグラフとツールへのポインタなどを保持するほかのデータと共に、メッセージ構造体に保存される。

テンポや拍子記号の変更などの特定のメッセージは、パフォーマンスによって直ちに処理され、解放される。ノートやパッチの変更など、その他のメッセージはキューに入れられ、タイム スタンプの順に処理される。

注 同じタイム スタンプのメッセージが特定の順序で処理されるという保証はない。

拍子記号メッセージは純粋な情報である。拍子記号はセグメントに組み込まれ、変更できない。

最終的に、メッセージは破棄されない限り、DirectMusic の出力ツールに到達する。このツールは受け取ったすべてのメッセージをスタンダード MIDI メッセージに変換し、それらをポート バッファ経由でシンセサイザに配信する。

解説については、「オーディオ データの流れの概要」を参照すること。


アプリケーションで作成されたメッセージ

ほとんどのメッセージはトラックによって生成されるが、アプリケーションで直接メッセージをキューに配置できる。たとえば、テンポを変更したり、DLS 音色でノートとしてサウンド エフェクトを演奏する場合に、この処理を行う。

次のメッセージはパフォーマンス メッセージを送信する。

DirectMusicPerformance8.SendCurvePMSG | カーブ
DirectMusicPerformance8.SendNotePMSG | 音楽のノート
DirectMusicPerformance8.SendPatchPMSG | パッチの変更
DirectMusicPerformance8.SendMIDIPMSG | その他の MIDI イベント
DirectMusicPerformance8.SendTempoPMSG | テンポの変更
DirectMusicPerformance8.SendTimeSigPMSG | 拍子記号の変更
DirectMusicPerformance8.SendTransposePMSG | 転調の変更

パフォーマンスが複数のオーディオパスを持つ場合、DirectMusic はアプリケーションが作成したメッセージを正しくルーティングできない場合がある。これは、新しいメッセージが属するオーディオパスに関する情報がメッセージに含まれていないからである。DirectX for Visual Basic では、アプリケーションで作成されたメッセージを特定のオーディオパスに送信する方法はない。


パフォーマンス メッセージのタイプ

DirectX for Visual Basic では、アプリケーションは、通知メッセージを除いて、送信されたメッセージにアクセスすることはできない。「通知とイベントの処理」を参照すること。


カーブ

カーブは、MIDI コントローラの一連の変更で構成され、値がなめらかにトランジションする。たとえば、ボリュームのフェードアウトまたはフェードインがある。

DirectMusicPerformance8.SendCurvePMSG で 1 つのパフォーマンス メッセージを送信することによって、カーブを実行できる。このメソッドに DMUS_CURVE_PMSG 型のメッセージを渡すことによって、カーブの開始時と終了時の値、期間、および形状を設定する。オプションで、コントローラが無効の場合に返されるリセット値を設定することもできる。

このメッセージ構造体の measure、offset、beat、grid、および mtOriginalStart メンバは、DirectMusic Producer セグメントによって送信されたメッセージ内で使用される。アプリケーションによって送信されたメッセージでは、これらの値は 0 になっている。

MergeIndex メンバは、変更が累積であるかオーバーライドであるかを示す。マージ インデックスが異なる場合、2 つのカーブ メッセージは累積される。マージ インデックスが同じ場合は、前のメッセージによる設定が新しいメッセージによって順次オーバーライドされる。

ccData メンバは、コントローラの変更の対象となる MIDI コントローラ番号を含み、空の場合は無視される。コントローラ番号については、MIDI の仕様を参照すること。

次のサンプル コードでは、現在のボリュームを 5 秒間でフェードアウトしている。

Dim curveMsg As DMUS_CURVE_PMSG

curveMsg.curveShape = DMUS_CURVES_LINEAR
curveMsg.mtDuration = 5000
curveMsg.Type = DMUS_CURVET_CCCURVE
curveMsg.ccData = 7  ' MIDI チャンネル ボリューム コントローラ
curveMsg.flags = DMUS_CURVE_START_FROM_CURRENT

dmPerf.SendCurvePMSG 0, _
  DMUS_PMSGF_REFTIME Or DMUS_PMSGF_LOCKTOREFTIME, _
  DMUS_PCHANNEL_BROADCAST_PERFORMANCE, curveMsg

注 より簡単にボリュームのフェードを実装するには、DirectMusicAudioPath8.SetVolume を使用する。このメソッドでは、常に、カーブに平行なシェイプを使用する。

次のコードでは、ピッチ ベンドを現在の値から 3 秒間の最大値に変更している。この時間内に、現在再生中のセグメントがほかのセグメントに置き換えられて無効になった場合は、ピッチは g_Pitch の値にリセットされる。

curveMsg.curveShape = DMUS_CURVES_LINEAR
curveMsg.startValue = 0  ' 現在位置から開始位置まで無視される。
curveMsg.endValue = 16383
curveMsg.mtDuration = 3000
curveMsg.Type = DMUS_CURVET_PBCURVE
curveMsg.ccData = 0
curveMsg.flags = DMUS_CURVE_RESET Or DMUS_CURVE_START_FROM_CURRENT
curveMsg.resetValue = g_Pitch
curveMsg.mtResetDuration = 0

dmPerf.SendCurvePMSG 0, _
  DMUS_PMSGF_REFTIME Or DMUS_PMSGF_LOCKTOREFTIME, _
  DMUS_PCHANNEL_BROADCAST_PERFORMANCE, curveMsg


MIDI メッセージ

ほとんどのアプリケーションは、MIDI メッセージを直接処理しない。ただし、アプリケーションはパフォーマンス メッセージとして MIDI コマンドを送信し、コントロール チェンジなどを行うことができる。

MIDI メッセージは、1 バイトのステータス バイトと、通常、1 バイトか 2 バイトのデータ バイトによって構成される。システム エクスクルーシブ MIDI メッセージは可変長である。

ステータス バイトはメッセージのタイプを示し、一部の状況では、そのメッセージを受け取るチャンネルを示す。ファイル中に同じ種類のイベントが続けて現れる場合は、ステータス バイトを省略できる。上位ビットが常に消去されているので、データ バイトを認識できる。ステータス バイトの上位ビットは、常に設定されている。

MIDI イベントのタイミングは、各メッセージの前にある数字で制御される。この値は、このイベントと最後のイベントの間隔を、ティック数で表している。ティックの実際の継続時間は、ファイル ヘッダーの時間の形式によって決定される。

注 MIDI メッセージが、ソース データに記述されている順序で処理されるという保証はない。DirectMusic メッセージはタイム スタンプの順に配信される。タイムが同一の MIDI メッセージが 2 つある場合は、予想と異なる順序で配信される場合がある。MIDI コンテンツをオーサリングするときに、イベントを発生させる順序が決まっている場合は、イベント間に間隔を入れるように注意する必要がある。たとえば、プログラム チェンジに依存するノートがある場合は、これらのノートとプログラム チェンジを同時に配置しない。

MIDI メッセージは、次の 2 つの主要なカテゴリに分類できる。

  • MIDI チャンネル メッセージ
  • MIDI システム メッセージ


MIDI チャンネル メッセージ

チャンネル メッセージは、音楽の 1 つのパートに対応する特定の MIDI チャンネルにアドレス指定される。

チャンネル メッセージは、モード メッセージかボイス メッセージのどちらかである。

モード メッセージは、チャンネルがそれ以降のボイス メッセージを取り扱う方法を決定する。たとえば、モード メッセージは、何か通知があるまではすべてのノートオン メッセージを無視して、無音状態を保つようチャンネルに指示することがある。

ほとんどのチャンネル メッセージはボイス メッセージである。これらはチャンネルにノートの演奏の開始または停止、何らかの方法でのノートの変更を指示し、チャンネルにほかの MIDI パッチ番号を割り当てることによりティンバーを変更する。

次の表は、ボイス メッセージの種類を示している。

ボイス メッセージ | 目的
ノートオン | ノートを演奏する。
ノートオフ | ノートの演奏を停止する。
コントロール チェンジ | ペダル、レバー、その他のデバイスからのデータを使って楽音を変更する。ボリュームやバンク セレクトなど、さまざまなコントロールにも使われる。
プログラム (パッチ) チェンジ | パッチ番号を割り当てることにより、チャンネルの音色を選択する。
アフタータッチ | キーのアフタータッチに従って、個別のノートまたはチャンネルのすべてのノートを変更する。
ピッチ ベンド チェンジ | チャンネルで演奏されるすべてのノートのピッチを変更する。

これらの説明は、スタンダード MIDI メッセージに適用され、パフォーマンス メッセージ形式に変換された MIDI データには適用されないことに注意する。たとえば、ノートの演奏を開始および停止するための 2 つの MIDI メッセージは、DirectMusic によって、ノートの継続時間を指定する 1 つのパフォーマンス メッセージに結合される。DirectMusic メッセージには、タイミングやルーティングに関する多くの追加情報も含まていれる。

MIDI ノート

ノートオン メッセージのデータ バイトは、ピッチとベロシティを表す。ほとんどの場合、ピッチの値 (キーナンバー) 0 は 2 オクターブ下の C 音 (MIDI では C0 と表記) であり、12 は 1 オクターブ下の C (MIDI の C1)、60 はピアノでいう中央の C (MIDI の C5) を意味する。ドラム キットの場合、データ バイトは特定のドラム サウンドを意味する。たとえば、GM (General MIDI) のパーカッション キー マップでは、値 60 はハイ ボンゴのサウンドを意味する。チャンネル 10 はドラム キットに予約されているので、シンセサイザはこのチャンネルでのノートオン メッセージをほかのチャンネルとは異なった方法で扱うことを知っている。

DirectMusic が MIDI ノートを変換する方法については、「ミュージック値と MIDI ノート」を参照すること。

プログラム チェンジ

プログラム チェンジとパッチ番号は、MIDI 再生と DirectMusic において重要な概念である。プログラム チェンジは特定の音色 (プログラムまたはティンバーとも呼ぶ) をチャンネルに割り当てるので、チャンネルに送信されたノートは適切なサウンドで演奏される。音色はパッチ番号によって識別される。GM 音色セットをロードする場合、パッチ番号 1 を指定するプログラム チェンジでは、チャンネルは必ずアコースティック グランド ピアノのノートで演奏される。スピーカで生成される実際のサウンドは、音色の合成方法に依存する。

バンク セレクト

プログラム チェンジの際に 1 バイトのデータ バイトを使ってパッチ番号を選択しているが、MIDI メッセージの各データ バイトで有効なのは 7 ビットだけなので、プログラム チェンジでは最大 128 の音色を選択することができる。より多くの選択肢を提供するために、MIDI 規格では最大 16,384 の音色バンクの使用が認められ、各バンクに最大 128 の音色を含めることができる。

ほかのバンクから音色を選択するには、MIDI シーケンサは最初にバンク セレクトと呼ばれるコントロール チェンジ メッセージを送信しなければならない。このメッセージのデータ バイトのうち 2 バイトを、最上位バイト (MSB) および最下位バイト (LSB) と呼び、これらを組み合わせてバンクを識別する。バンクを選択した後、それ以降のプログラム チェンジではそのバンクから音色が選択される。

DirectMusic パッチ番号

ここでは、C++ でのアプリケーション開発について説明する。DirectX for Visual Basic では、DirectMusicPerformance8.SendPatchPMSG メソッドを使う方法を除いて、アプリケーションでパッチ番号を変更することはできない。


MIDI システム メッセージ

システム メッセージは、どのチャンネルにとっても排他的ではない。これらは次の表のように 3 種類に分類される。

メッセージ タイプ | 目的
システム共通 | さまざまなコマンドとデータ
システム エクスクルーシブ | 機器固有のコマンドとデータ
システム リアルタイム | クロックベースの MIDI 機器の同期化

ほかの MIDI メッセージとは異なり、システム エクスクルーシブ メッセージは任意の長さのデータ バイトを保持できる。データを送信した後で、シーケンサは EOX と呼ばれるシステム共通メッセージを送信し、システム エクスクルーシブ メッセージの終わりを知らせる。

DirectX for Visual Basic では、アプリケーションがシステム エクスクルーシブ メッセージに直接アクセスすることはできない。


DirectMusic ポートの使い方

ここでは、C++ でのアプリケーション開発について説明する。DirectX for Visual Basic では、ポートへの直接アクセスはサポートされない。


デフォルト ポート

ここでは、C++ でのアプリケーション開発について説明する。DirectX for Visual Basic では、ポートへの直接アクセスはサポートされない。


カスタム ロード

ここでは、C++ でのアプリケーション開発について説明する。DirectX for Visual Basic では、標準的な DirectMusic オブジェクトのロードだけがサポートされる。


音色コレクションの使い方

ほとんどのアプリケーションでは、DLS 音色データはバンドに関連付けられ、バンドがダウンロードされたときにシンセサイザにダウンロードされる。詳細については、「バンドの使い方」を参照すること。

音色コレクションを直接操作する方法については、次のトピックを参照すること。

  • コレクションのロードとダウンロード


コレクションのロードとダウンロード

音色のコレクションをロードするには、DirectMusicLoader8.LoadCollection または DirectMusicLoader8.LoadCollectionFromResource メソッドを呼び出す。これらのメソッドは DirectMusicCollection8 オブジェクトを返す。このオブジェクトにメソッドはなく、パラメータとして DirectMusicSegment8.ConnectToCollection に渡すためにだけ使用する。このメソッドを呼び出してコレクションをセグメントに関連付け、次に、DirectMusicSegment8.Download を呼び出して音色をダウンロードする。例については、「カスタム音色による MIDI ファイルの演奏」を参照すること。

これらの手順は、デフォルト以外のコレクションを使用する場合にのみ必要となる。セグメントがコレクションを参照しない場合、通常は DirectMusicSegment8.Download を呼び出すときに、セグメント中にオーサリングされたデフォルト コレクションの音色、または General MIDI セットの音色がポートにダウンロードされる。バンドをダウンロードするときに、そのバンドの音色で必要なすべての DLS データがダウンロードされる。「バンドの使い方」を参照すること。


音色の操作

ここでは、C++ でのアプリケーション開発について説明する。DirectX for Visual Basic では、アプリケーションがコレクションの個々の音色を操作することはできない。


下位レベル DLS

ここでは、C++ でのアプリケーション開発について説明する。DirectX for Visual Basic では、下位レベルでの DLS データの操作はサポートされていない。


DirectMusic ツール

ここでは、C++ でのアプリケーション開発について説明する。DirectX for Visual Basic では、アプリケーション定義のツール、またはサードパーティ製のツールはサポートされない。


プロパティ セット

ここでは、C++ でのアプリケーション開発について説明する。DirectX for Visual Basic では、プロパティ セットへのアクセスは提供されない。


DirectMusic ポートのプロパティ セット

ここでは、C++ でのアプリケーション開発について説明する。DirectX for Visual Basic では、プロパティ セットへのアクセスは提供されない。


DirectSound バッファのプロパティ セット

ここでは、C++ でのアプリケーション開発について説明する。DirectX for Visual Basic では、プロパティ セットへのアクセスは提供されない。


DirectSound の性能の最適化

ここでは、DirectSound バッファで直接オーディオ データを演奏するアプリケーションの性能を向上させるためのさまざまなヒントを示す。説明するトピックは、次のとおりである。

  • バッファ フォーマットのマッチング
  • ハードウェア ミキシングの利用
  • ダイナミック ボイス管理
  • ISA および PCI カードでのハードウェア アクセラレーション
  • プライマリ バッファの連続再生
  • コントロールの変更の最少化
  • 3D バッファに関係する CPU の考慮事項


バッファ フォーマットのマッチング

DirectSound ミキサは、各セカンダリ サウンド バッファから得たデータをプライマリ サウンド バッファ用のフォーマットに変換する。この変換はデータをプライマリ バッファにミキシングする際にその場で行われ、CPU サイクルを消費する。セカンダリ バッファとプライマリ バッファで同じフォーマットを使用することで、この負荷を回避できる。通常、これは、プライマリ バッファのフォーマットを、データで使用されるウェーブ ファイルのフォーマットに設定することである。

DirectSound の採用するフォーマット変換方法では、サンプリング レートとチャンネル数を合わせるだけでよい。サンプリング サイズ (8 ビットか 16 ビットか) は関係ない。


ハードウェア ミキシングの利用

ほとんどのサウンドカードは、対応する DirectSound ドライバが存在すれば、何らかのレベルのハードウェア ミキシングをサポートする。次のヒントは、ハードウェア ミキシングをできるだけ利用するのに役立つ。

  • 実行時に DirectSound8.GetCaps メソッドを呼び出して、サウンドアクセラレータ ハードウェアがサポートしているフォーマットを確認し、できる限りそのフォーマットを使う。
  • 最も利用の多いサウンドのサウンド バッファを最初に作成する。ハードウェアでミキシングできるバッファ数には限度がある。
  • バッファをハードウェアに必ず作成するには、DSBUFFERDESC 型の lFlags メンバに DSBCAPS_LOCHARDWARE フラグを指定する。このフラグを指定し、ハードウェア ミキシングに対するリソースが利用できない場合は、DirectSound8.CreateSoundBuffer メソッドは失敗する。
  • ボイス管理を使って、ハードウェア リソースが利用可能なときにバッファをリソースに割り当てたり、あまり重要でないバッファを強制終了させてハードウェア リソースを解放できるようにする。「ダイナミック ボイス管理」を参照すること。


ダイナミック ボイス管理

多くのサウンド カードは固有のセカンダリ バッファを維持し、3D エフェクトとそのミキシングを処理する。これらのハードウェア バッファは、呼び出しの際、通常はカード自体ではなくシステム メモリに配置される。しかし、これらはデバイスによってミキシングされるので、システム プロセッサに対する要求は、ソフトウェア バッファよりもはるかに少なくなる。したがって、ハードウェアにできる限り多くのバッファ、特に 3D バッファを割り当てることが最も効率的である。

デフォルトでは、DirectSound は可能であれば常にバッファをハードウェアに割り当てる。しかし、DirectSound はデバイスが一度に再生できるだけのハードウェア バッファしか作成できない。つまり、ハードウェア バッファ数は、利用可能なハードウェア ボイスで制限される。DirectSound は、バッファが作成されるときにハードウェア ボイスを割り当て、バッファが不要になったときだけ解放する。ボイスは、バッファが再生中でないときもフリーではない。アプリケーションが多くのバッファを作成する場合、いくつかのバッファがソフトウェアに存在する可能性がある。つまり、サウンド カードではなく CPU でバッファの管理とミキシングが行われる。

ダイナミック ボイス管理を使うと、バッファが再生されるまでボイス割り当てを遅延したり、DirectSound が優先順位の低いサウンドを早めに停止してリソースを新しいサウンドに割り当てることにより、ハードウェア リソースの利用制限を克服できる。

ハードウェア ミキシングと 3D エフェクトに対するリソースの割り当てをバッファが再生されるまで遅延するには、DirectSound8.CreateSoundBuffer、DirectSound8.CreateSoundBufferFromFile、または DirectSound8.CreateSoundBufferFromResource に渡される DSBUFFERDESC 型に DSBCAPS_LOCDEFER フラグを指定する。DSBCAPS_LOCDEFER フラグによって作成されたバッファについて DirectSoundSecondaryBuffer8.Play または DirectSoundSecondaryBuffer8.AcquireResources を呼び出す場合、DirectSound は可能であればハードウェアにバッファを配置し、それ以外の場合はソフトウェアに配置する。

Play を呼び出す場合は、次の表に示すフラグの 1 つ、または最初の 2 つのフラグのどちらかを 3 番目のフラグと組み合わせて渡すことで、バッファに対するハードウェア ボイスの解放を試みることができる。その後、DirectSound はフラグの指定する終了基準に適した再生バッファを検索する。

フラグ | 基準
DSBPLAY_TERMINATEBY_TIME | どの候補バッファよりも長く再生されているバッファを選択する。
DSBPLAY_TERMINATEBY_DISTANCE | リスナーから最も遠い 3D の候補バッファを選択する。
DSBPLAY_TERMINATEBY_PRIORITY | Play の呼び出しでの設定に基づき、候補バッファのうち最も優先度の低いバッファを選択する。このフラグをほかの 2 つのフラグのどちらかと組み合わせると、そのフラグは優先度が等しい場合だけに使われる。

適切なバッファが見つかると、DirectSound はそのバッファを停止し、使用していたボイスを新たに再生されるバッファに割り当てる。どのバッファも終了基準に適していない場合は、DSBPLAY_LOCHARDWARE フラグが指定されていなければ、新たに再生されるバッファはソフトウェアで再生される。このフラグが指定されている場合、Play に対する呼び出しは失敗する。

遅延バッファの再生時の処理についての詳細は、「DirectSoundSecondaryBuffer8.Play」を参照すること。

注 バッファの作成時は、DSBCAPS_LOCDEFER フラグを DSBCAPS_STATIC フラグと組み合わせて使わないこと。いくつかの PCI カードの場合のように、オンカード メモリが利用可能なとき、DSBCAPS_STATIC バッファはこのメモリに置かれる。DSBCAPS_LOCDEFER フラグでこのようなバッファを作成する場合、バッファ メモリはバッファが最初に再生されるまでサウンド カードにコピーされず、不適切な遅れが生じる。詳細については、「ISA および PCI カードでのボイス管理」を参照すること。


ISA および PCI カードでのハードウェア アクセラレーション

過去数年間に、サウンド カードは ISA バス カードから PCI カードに移行した。この設計の変更により、DirectSound をアクセラレートするカードがオーディオ データを処理する基本的な方法が変化した。さらに、DirectSound にボイス管理が導入され、アプリケーションは限られたハードウェア アクセラレーション リソースを効率的に使用できるようになった。

ここでは、2 種類のサウンド カードで、バッファを割り当てたり、ボイス管理を使う際の注意事項を説明する。説明するトピックは、次のとおりである。

  • ISA カード上の DirectSound バッファ
  • PCI カード上の DirectSound バッファ
  • ISA および PCI カードでのボイス管理


ISA カード上の DirectSound バッファ

DirectSound が最初に導入されたとき、すべてのオーディオ デバイスは ISA バス上で動作していた。ISA バスは、システム全体の性能に大きな影響を与えることなく、16 ビット、22 kHz ステレオ データを CPU からサウンド カードにストリーミングするには十分であった。しかし、より多くのデータを送信しようとすると、バスに過度の負荷がかかる場合があった。この制限によって、オーディオ ハードウェアの設計は大きく影響されていた。

DirectSound バッファをミキシングするために、サウンド カード上のチップで 2 とおりの処理を行うことができる。ISA バスを介してシステム メモリにアクセスするか、カード自体の専用メモリを使用するかである。ISA バスの帯域幅は限られているので、システム メモリからのオーディオ データの読み込みは現実的ではない。したがって、ISA ベースのサウンド カードで、DirectSound アクセラレーションを実行するカードは、ほとんどの場合専用のオンボード RAM を持っている。

このようなサウンド カードを使って DirectSound をアクセラレートする場合、まずサウンド データをシステム メモリから、ISA バスを介してカード上の専用メモリにコピーしなければならない。このコピーには若干時間がかかる場合がある。しかし、データをカードにコピーした後は、システムに対してサウンドの開始、停止、ミキシングの負荷はほとんどかからない。このような処理はすべて、カード上の専用メモリにアクセスするオーディオ プロセッサ チップによって処理される。

ISA ベースの DirectSound アクセラレータはカード上のスタティック バッファをサポートしているが、ストリーミング バッファはサポートしていない。これは、低速の ISA バスを介してデータをストリーミングするのは実用的ではないからである。DSBCAPS_STATIC フラグを指定して作成した DirectSound バッファは、カードにメモリが搭載されている場合、そのメモリに配置される。その他のバッファは、システム メモリに作成される。


PCI カード上の DirectSound バッファ

現在販売されているほとんどのオーディオ カードは PCI バスに接続するように設計されている。PCI バスが一般的になるに従って、システムとオーディオ カードとの間で利用可能な帯域幅が大幅に増加した。現在では、オーディオ チップが直接システム メモリにアクセスし、オーディオ データを取得してハードウェア ミキシングを行うことも現実的になった。その結果、バッファ用のオンボード メモリを持つ意味がなくなった。

PCI カードでは、スタティック バッファとストリーミング バッファは事実上同じである。すべてのバッファはシステム メモリ内に配置されるので、DSBCAPS_STATIC フラグはバッファの場所に影響しない。

注 ほとんどのサウンド カードは、オンボード RAM を持っていない場合でも、スタティック バッファを持っていると DSCAPS にレポートする。これらのカードによってレポートされるストリーミング バッファとスタティック バッファは同じバッファである場合がある。


ISA および PCI カードでのボイス管理

バッファの作成時に DSBCAPS_LOCDEFER フラグを使うことによって、バッファが再生されるときまで、ハードウェア ミキシング メモリまたはソフトウェア ミキシング メモリへのバッファの割り当てを遅延することができる。詳細については、「ダイナミック ボイス管理」を参照すること。

アプリケーションの性能に対する遅延割り当ての効果は、ユーザーのシステムでの DirectSound アクセラレータのタイプによって異なる。

PCI アクセラレータの場合を考えてみる。遅延バッファを再生するときに、DirectSound はサウンドの再生に利用できるハードウェアがあるかどうかを調べる。ハードウェアを利用できる場合、DirectSound は元の場所にあるサウンド データにアクセスできるかどうかを確認する。最後に、DirectSound は再生を開始するようにハードウェアに指示する。この処理は、効率的であり、また高速である。

注 DirectSound ボイス マネージャは、メモリではなく、ハードウェア ミキシング リソースを割り当てる。PCI カードでは、バッファはハードウェア ミキサとソフトウェア ミキサのいずれに割り当てられるかに関係なく、割り当ての前後で同じメモリを使用する。

ユーザーが ISA ベースのアクセラレータを使用する場合、状況はまったく異なる。この場合、オーディオ データをハードウェア ミキシング バッファに取り込む処理は非常に遅い。オーディオ データをミキシングするには、ISA バスを介して、サウンド カード上のメモリにデータをロードしなければならないからである。遅延バッファの場合、再生の呼び出しが行われた後、サウンドが開始される前に不適切な遅延が発生する。このような理由から、ISA ベースの DirectSound アクセラレータ カードではボイス管理の使用は推奨されていない。

ISA デバイスでアプリケーションがボイス管理を使わないようにすることは簡単である。DSBCAPS_STATIC フラグを設定しない限り、バッファはオンボード メモリに割り当てられない。したがって、DSBCAPS_STATIC と DSBCAPS_LOCDEFER を組み合わせない限り、再生時にバッファがオンボード メモリに割り当てられる危険性はない。

DSBCAPS_STATIC だけを指定すると、バッファは ISA カード上の既存のメモリを利用するが、PCI カードの場合は何の効果もない。この場合、ほかのフラグが指定されていないと、DirectSound はバッファをハードウェアの制御下に置くが、システム メモリを利用する。DSBCAPS_LOCDEFER だけを指定すると、ISA カードでは何の効果もない。バッファは常にシステム メモリに配置され、ハードウェアによって管理されないからである。

次の表に、ISA および PCI デバイス用に作成されたバッファに対する DSBCAPS_STATIC および DSBCAPS_LOCDEFER フラグの効果をまとめる。

カード | フラグ | メモリ | HW アクセラレーション
ISA | DSBCAPS_STATIC | 利用可能な場合はハードウェア。 | ハードウェア メモリにある場合は可。
PCI | DSBCAPS_STATIC | システム。 | ハードウェア ボイスが利用可能な場合は可。フラグの効果はない。
ISA | DSBCAPS_LOCDEFER | 利用可能で、DSBCAPS_STATIC が設定されている場合はハードウェア。 | ハードウェア メモリにある場合は可。ただし、最初の再生には待ち時間が発生する。
PCI | DSBCAPS_LOCDEFER | システム。 | ハードウェア ボイスが利用可能な場合は可。

遅延割り当てによる問題を回避しながら、ISA カードでアクセラレーションを利用するには、まずデバイスの能力をチェックする。カードに 1 つ以上のスタティック バッファがあり、ストリーミング バッファがないとレポートされる場合は、オンボード メモリを搭載した古い ISA カードである可能性が高い。この場合、DSBCAPS_STATIC フラグを使うことができるがDSBCAPS_LOCDEFER を使ってはならない。カードに 1 つ以上のストリーミング バッファがあるとレポートされる場合は、新しい PCI ベースのアクセラレータ カードである。この場合は、ハードウェア ボイスを最大限に利用するために、DSBCAPS_LOCDEFER を使用し、DSBCAPS_STATIC を使用しない。


プライマリ バッファの連続再生

サウンドが再生されていない場合、DirectSound はミキサ エンジンを停止し、DMA (ダイレクト メモリ アクセス) を停止させる。再生なしの状態が頻繁に発生するアプリケーションでは、サウンドを再生するたびにミキサの開始と停止を行う場合のオーバーヘッドは、ミキサを常時アクティブにする場合の DMA のオーバーヘッドより大きくなることがある。また、サウンド機器やドライバによっては、再生の頻繁な開始と停止により不要な雑音を出すこともある。

アプリケーションがほぼ連続的に再生を行い、休止時間が少ない場合は、DirectSoundPrimaryBuffer8.Play メソッドを呼び出し、ミキサ エンジンを常時アクティブにもできる。

サウンドの再生がないときにミキサ エンジンを停止するデフォルトの状態に戻すには、DirectSoundPrimaryBuffer8.Stop メソッドを呼び出す。

プライマリ バッファ オブジェクトを取得するには、DirectSound8.CreatePrimarySoundBuffer メソッドを使う。


コントロールの変更の最少化

セカンダリ バッファのパン、ボリューム、周波数を変更すると性能に影響する。サウンド出力が途切れることを防止するには、DirectSound ミキサは 20ms から 100ms、またはそれ以上先行してミキシングを行わなければならない。コントロールを変更した場合は、ミキサは先行ミキシング バッファをフラッシュ (解放) し、変更後のサウンドを使って再ミキシングを行わなければならない。

送信するコントロールの変更回数を最少にすることは良い考えである。DirectSoundSecondaryBuffer8.SetVolume、DirectSoundSecondaryBuffer8.SetPan、DirectSoundSecondaryBuffer8.SetFrequency の各メソッドを使うルーチンの呼び出し回数を減らすよう努める。たとえば、アニメーションのフレームに同期して音を左スピーカから右スピーカへ動かすルーチンを使っている場合、SetPan メソッドを 1 フレームごとに 2 回ではなく 1 回呼び出すことを試みる。

注 3D コントロール (向き、位置、速度、ドップラー係数など) を変更した場合も、DirectSound ミキサは先行ミキシング バッファを再ミキシングしなければならない。しかし、3D コントロールの変更をグループ化し、再ミキシングを 1 回に削減できる。「遅延設定」を参照すること。


3D バッファに関係する CPU の考慮事項

ソフトウェアによる 3D バッファのエミュレーションは、多くの計算処理を要する。アプリケーションで、いつ、どのように 3D バッファを使用するかを決定する場合は、このことを考慮しなければならない。

3D サウンドの利用は最小限に抑え、3D エフェクトが利点とならないサウンドには 3D サウンドを適用しない。各サウンドの 3D エフェクトを簡単に有効または無効にできるようアプリケーションを設計する。任意の 3D サウンド バッファに対する 3D 処理を停止するには、DS3DMODE_DISABLE フラグを指定して DirectSound3DBuffer8.SetMode メソッドを呼び出す。

リスナーからの距離が遠く、聞こえないバッファについても、3D 処理が停止していることを確認できる。「最小距離と最大距離」を参照すること。


DirectSound ドライバ モデル

VxD ドライバ モデルでは、DirectSound のすべてのミキシングは、仮想デバイス ドライバ Dsound.vxd で処理される。Dsound.vxd は、サウンド カードがホスト CPU からデータを受信するために使用する実際の DMA バッファへのアクセスも提供する。これは DirectSound プライマリ バッファと同じである。DirectSound アプリケーションは、サンプリング レートやビット深度など、プライマリ バッファの特定のプロパティを設定することができ、したがってハードウェア自体のプロパティも変更できる。

Windows Driver Model (WDM) では、DirectSound は、ハードウェアによってアクセラレートされたバッファの場合を除いて、サウンド バッファに直接アクセスしない。その代わりに、DirectSound はカーネル ミキサ、つまり Kmixer と通信する。Kmixer の役割は、複数のオーディオ ストリームのフォーマットを共通のフォーマットに変換し、これらをミキシングして、その結果をハードウェアに送信することである。つまり、Dsound.vxd が行っていた処理を行っている。大きな違いは、Dsound.vxd が DirectSound バッファのデータだけをミキシングするのに対して、Kmixer は、Win32 waveOut 関数を使うアプリケーションからのデータを含む、すべての Windows オーディオ データをミキシングすることである。DirectSound とウェーブフォーム オーディオ出力デバイスを同時にオープンできないという規則は、WDM ドライバを使用するシステムには当てはまらない。

Kmixer とオーディオ ハードウェアとの関係は特に重要である。Kmixer は、システム上で、ハードウェアの DMA バッファのフォームを指定できる唯一のソフトウェアである。Kmixer は、ミキシングを要求されたサウンドに基づいてフォーマットを選択する。出力フォーマットは、ミキシングを要求されたサウンドの最高品質のフォーマットか、ハードウェアでサポートされている、それに最も近いフォーマットに設定される。

これは、とても重要な意味を持っている。DirectSound では、ハードウェアの DMA バッファのフォーマットを設定できないということである。アプリケーションでは、ハードウェア フォーマットは実際に演奏されるデータに基づくことを意味する。44 kHz のファイルを再生する場合、Kmixer は最大 44 kHz のすべてのデータをミキシングし、ハードウェアが 44 kHz で実行されていることを確認する。

アプリケーション開発者は、使用されるドライバ モデルを選択しない。ドライバ モデルは、サウンド カードの種類、Windows のバージョン、ユーザーがインストールしている特定のドライバによって決まる。このような理由から、アプリケーションをテストするときに、すべての可能性を調べておくことが重要である。DirectSound は Dsound.vxd を使用する場合もあれば、Kmixer を使用する場合もあるので、アプリケーションの動作および性能がいずれの場合も許容できるものであることを確認しなければならない。


プライマリ バッファへの書き込み

アプリケーションでは、協調レベルが DSSCL_WRITEPRIMARY に設定されている場合、DirectSoundPrimaryBuffer8.WriteBuffer メソッドを使用して、プライマリ バッファに直接書き込むことができる。ただし、DirectX for Visual Basic アプリケーションでは実行しないことを強く推奨する。


プログラミングのヒントおよびツール

ここでは、DirectX Audio アプリケーションを効率的に開発するための情報を記述する。説明するトピックは、次のとおりである。

  • DirectX Audio プロジェクトのデバッグ
  • テスト用の DirectSound アクセラレーションのコントロール


DirectX Audio プロジェクトのデバッグ

ここでは、C++ でのアプリケーション開発について説明する。


テスト用の DirectSound アクセラレーションのコントロール

コントロール パネルの [サウンドとマルチメディアのプロパティ] ページで、システム上の DirectSound の性能を調整できる。[オーディオ] タブの [再生] の [詳細] をクリックする。[パフォーマンス] タブをクリックする。スライダを使って、ハードウェア アクセラレーションを次のいずれかに設定できる。

最大
IKsPropertySet 拡張機能など、すべての DirectSound アクセラレーションを有効にする。Windows 98 では、これがデフォルトの設定である。
標準
DirectSound セカンダリ バッファのアクセラレーションを有効にするが、ハードウェア固有の IKsPropertySet 拡張機能を無効にする。Windows 2000 では、これがデフォルトの設定である。
基本
DirectSound セカンダリ バッファのハードウェア アクセラレーションを無効にする。このオプションは、テスト用にアクセラレーション機能を持たないサウンド カードをエミュレーションする場合に便利である。
なし
DirectSound をエミュレーション モードにする。このモードは、システムに DirectSound 互換のドライバがないものとして機能する。すべてのミキシングは、ユーザー モードの DirectSound によって行われ、ミキシングされたデータは Win32 ウェーブフォーム オーディオ関数に送信される。通常、これによって遅延時間が大幅に増加する。


DirectX Audio Visual Basic チュートリアル

ここでは、次のチュートリアルを使用して、Visual Basic® アプリケーションに Microsoft® DirectMusic® および Microsoft® DirectSound® を実装する方法を説明する。

  • チュートリアル 1 : オーディオ ファイルの再生
  • チュートリアル 2 : オーディオパスの使い方

このほかに、SDK と共に提供されるサンプル アプリケーションでは、Microsoft® DirectX® Audio のより専門的な使い方が示されている。これらのサンプルの説明については、「DirectX Audio Visual Basic サンプル」を参照すること。


チュートリアル 1 : オーディオ ファイルの再生

このチュートリアルでは、DirectX Audio の最も基本的なタスクを実行する方法を記述する。具体的には、DirectMusic パフォーマンスの初期化とオーディオ ファイルの再生について説明する。このチュートリアルは、次のステップから構成されている。

  • ステップ 1 : オーディオ システムの設定
  • ステップ 2 : ファイルのロード
  • ステップ 3 : ファイルの再生
  • ステップ 4 : 終了処理

チュートリアルで使用しているサンプル コード全体のファイルが次のフォルダにある。

\mssdk\samples\Multimedia\VBSamples\DirectMusic\Tutorials\Tut1

注 DirectX SDK がインストールされているルート ディレクトリが異なる場合は、パス内の "mssdk" をそのディレクトリの名前に置き換える必要がある。


ステップ 1 : オーディオ システムの設定

このサンプル アプリケーションでは、次のオブジェクト変数を宣言する。

Private dx As New DirectX8
Private dml As DirectMusicLoader8
Private dmp As DirectMusicPerformance8
Private seg As DirectMusicSegment8

これらのオブジェクトのうち、宣言時に初期化できるのは、DirectX8 オブジェクトだけである。DirectMusicLoader8 および DirectMusicPerformance8 は、次のように、このオブジェクトのメソッドを使って作成する必要がある。

Set dml = dx.DirectMusicLoaderCreate
Set dmp = dx.DirectMusicPerformanceCreate

作成したパフォーマンスは初期化しなければならない。DirectMusicPerformance8.InitAudio メソッドは、次のタスクを実行する。

  • DirectSound8 オブジェクトを作成する。通常、このオブジェクトに変数は必要ない。DirectSound パラメータとして Nothing を渡すか、このパラメータを省略することができる。
  • アプリケーション ウィンドウを DirectSound に関連付ける。通常、メイン アプリケーション ウィンドウのハンドルは、hwnd パラメータとして渡される。
  • 標準タイプのデフォルトのオーディオパスを設定する。このチュートリアルでは、音楽に適した DMUS_APATH_SHARED_STEREOPLUSREVERB 型のパスを要求する。
  • パフォーマンス チャンネルの数をオーディオパスに割り当てる。ウェーブ ファイルに必要なパフォーマンス チャンネルは 1 つだけである。MIDI ファイルは 16 個のチャンネルを必要とする。DirectMusic Producer で作成したセグメントは、さらに多くのチャンネルを使用する場合がある。余分のチャンネルを要求しても問題は生じない。
  • シンセサイザの機能およびリソースを指定する。これは、次の 2 つの方法で行うことができる。フラグを設定するか、DMUS_AUDIOPARAMS 型で詳細な情報を指定する。ほとんどのアプリケーションは、DMUS_AUDIOF_ALL フラグを設定して、DirectMusic によってデフォルトのパラメータ設定のシンセサイザが作成されるようにしている。DMUS_AUDIOPARAMS 型をメソッドに渡す必要があるが、DMUS_AUDIOPARAMS 型サンプルにあるように、これを空白にしておくことができる。

サンプル アプリケーションでは、非常に簡単な方法で InitAudio を呼び出している。

dmp.InitAudio Me.hWnd, DMUS_AUDIOF_ALL, dmA, Nothing, _
         DMUS_APATH_SHARED_STEREOPLUSREVERB, 64

次の「ステップ 2 : ファイルのロード」に続く。


ステップ 2 : ファイルのロード

前のステップで作成した DirectMusicLoader8 オブジェクトは、アプリケーションの実行時にいつでもファイルからサウンド データをロードするために使用できる。

データを取得するには、ローダーにデータの場所を指示する必要がある。ファイルをロードするたびにフル パスを指定することもできるが、デフォルトのディレクトリを設定しておく方が便利である。これを行うには、DirectMusicLoader8.SetSearchDirectory メソッドを使用する。サンプル アプリケーションは、FindMediaDir 関数によって返されたパスを使用する。この関数は、サンプル ファイルが格納されているディレクトリを検索する。これによってディレクトリの場所がわかれば、ローダーは、ディレクトリ名を指定されなくても、サンプル ファイルをロードできる。

dml.SetSearchDirectory FindMediaDir("sample.sgt", True)

ローダーは、ファイルをロードして、それを DirectMusicSegment8 オブジェクトとして返す。

Set seg = dml.LoadSegment("sample.sgt")

次の「ステップ 3 : ファイルの再生」に続く。


ステップ 3 : ファイルの再生

次に、前のステップでロードしたファイルを DirectMusicSegment8 オブジェクトとしてパフォーマンスに渡す。

MIDI ファイルまたは DirectMusic Producer セグメント ファイルからセグメントをロードするには、バンドをシンセサイザにダウンロードしておく必要がある。バンドをダウンロードしない場合、このステップは、固有のバンドを使用するセグメントごとに 1 回だけ実行する。

サンプル アプリケーション内の次のコードは、デフォルトのオーディオパスにバンドをダウンロードする。オーディオパスの代わりにパフォーマンスにダウンロードすることもできる。使用するシンセサイザが 1 つだけの場合は、ダウンロード先としてどちらのオブジェクトを選択してもかまわない。

seg.Download dmp.GetDefaultAudioPath

ファイルを再生するには、DirectMusicPerformance8.PlaySegmentEx にセグメント オブジェクトを渡す。このメソッドには多数の再生オプションが用意されている。ただし、デフォルトのオーディオパスで直ちにセグメントを再生するには、サンプル アプリケーションの次のコードのように、2 番目以降のパラメータをすべて 0 に設定するか、省略する。

dmp.PlaySegmentEx seg, 0, 0

次の「ステップ 4 : 終了処理」に続く。


ステップ 4 : 終了処理

オーディオ アプリケーションを正常に終了するには、次の 3 つの主な手順を実行する必要がある。

  • DirectMusicPerformance8.StopEx を呼び出して、再生中のセグメントをすべて停止する。
  • パフォーマンスの終了処理を行う。DirectMusicPerformance8.CloseDown メソッドは、さまざまなクリーンアップ タスクを実行して、オブジェクトへの内部参照を解放する。
  • オブジェクトの変数を Nothing に設定して、すべてのオブジェクトを解放する。

サンプル アプリケーション内の次のプロシージャは、DirectX Audio の終了処理を行う。

Private Sub Form_Unload(Cancel As Integer)
    If Not (seg Is Nothing) Then
        dmp.StopEx dmp.GetDefaultAudioPath, 0, 0
    End If
    Set seg = Nothing
    dmp.CloseDown
    Set dmp = Nothing
    Set dml = Nothing
    Set dx = Nothing
End Sub


チュートリアル 2 : オーディオパスの使い方

このチュートリアルは、デフォルト以外のオーディオパスを使用する DirectX Audio アプリケーションを設定する方法を示す。また、オーディオパスのボリュームを設定する方法と、オーディオパスからオブジェクトを取得してパラメータを設定する方法も示す。この場合は、DirectSound3DBuffer8 オブジェクトを取得して、空間内にサウンドを配置する。

このチュートリアルは、次のステップから構成されている。

  • ステップ 1 : DirectX オブジェクトの作成
  • ステップ 2 : オーディオ環境の初期化
  • ステップ 3 : オーディオパスの作成
  • ステップ 4 : セグメントのロード
  • ステップ 5 : バンドのダウンロード
  • ステップ 6 : オーディオパスでのサウンドの再生
  • ステップ 7 : サウンドの停止
  • ステップ 8 : オーディオパス パラメータの設定
  • ステップ 9 : 3D パラメータの設定

チュートリアルで使用しているサンプル コード全体のファイルが次のフォルダにある。

\mssdk\samples\Multimedia\VBSamples\DirectMusic\Tutorials\Tut2

注 DirectX SDK がインストールされているルート ディレクトリが異なる場合は、パス内の "mssdk" をそのディレクトリの名前に置き換える必要がある。


ステップ 1 : DirectX オブジェクトの作成

最初のステップでは、DirectX8 オブジェクトを作成し、作成したオブジェクトを使って DirectMusicLoader8 および DirectMusicPerformance8 を作成する。

これらのオブジェクトの変数は、次のように宣言される。

Private dx As DirectX8
Private dml As DirectMusicLoader8
Private dmp As DirectMusicPerformance8

また、後で使用するために、次のグローバル変数も宣言する。

Private dmSeg As DirectMusicSegment8
Private dmSegState As DirectMusicSegmentState8
Private dmPath As DirectMusicAudioPath8

最初の 3 つのオブジェクトは、Form_Load プロシージャで作成される。エラーが発生しても、各作成メソッドの試行が完了するまで無視される。エラーが発生すると、1 つのメッセージ ボックスが表示されて、アプリケーションが終了する。

Private Sub Form_Load()

    Dim dmA As DMUS_AUDIOPARAMS
    MediaPath = FindMediaDir("tuta.wav")

    On Local Error Resume Next

    Set dx = New DirectX8
    Set dml = dx.DirectMusicLoaderCreate
    Set dmp = dx.DirectMusicPerformanceCreate

Form_Load プロシージャは、次の「ステップ 2 : オーディオ環境の初期化」に続く。


ステップ 2 : オーディオ環境の初期化

サンプル アプリケーションは、前のステップに続いて Form_Load プロシージャで検索ディレクトリを設定し、サウンド ファイルを探す場所をローダーに指示する。

    dml.SetSearchDirectory MediaPath

次に、パフォーマンスを初期化する。DMUS_AUDIOPARAMS 型を空白のままにすると、パフォーマンスはデフォルトのパラメータを使用して初期化される。デフォルトのオーディオパスは要求されない。

    dmp.InitAudio Me.hWnd, DMUS_AUDIOF_ALL, dmA

次に、オブジェクトの作成または初期化の間に発生したエラーを処理する。

    If Err.Number <> 0 Then
        MsgBox "Could not initialize DirectMusic." & vbCrLf & _
            "This sample will exit.", vbOKOnly Or vbInformation, _
            "Exiting..."
        Unload Me
        Exit Sub
    End If

Form_Load プロシージャは次の「ステップ 3 : オーディオパスの作成」に続く。


ステップ 3 : オーディオパスの作成

DirectMusicPerformance8.InitAudio の呼び出しでは、デフォルトのオーディオパスは指定されていない。その代わり、サンプル アプリケーションは、標準オーディオパスを作成して、そこでセグメントを再生する。より複雑なアプリケーションでは、複数のオーディオパスを作成する場合がある。たとえば、音楽用に 1 つと 3D サウンド エフェクト用に 1 つ作成する。このチュートリアルでは、DMUS_APATH_DYNAMIC_3D 型のオーディオパスを 1 つだけ使用する。この型のオーディオパスは、リバーブなどのエフェクトは配置できないが、単純なサウンド エフェクトに適している。

    Set dmPath = dmp.CreateStandardAudioPath(DMUS_APATH_DYNAMIC_3D, _
                                             64, True)
End Sub  ' Form_Load

このオーディオパスは、最大 64 個のパフォーマンス チャンネルをサポートでき、作成時にアクティブになる。

次の「ステップ 4 : セグメントのロード」に続く。


ステップ 4 : セグメントのロード

これまでのステップで、アプリケーションがサウンドをロードおよび再生するために必要なすべてのオブジェクトが用意された。このサンプルでは、[Play] ボタンがクリックされるたびに、ユーザーが選択したファイルの種類に応じて 3 つのサウンド ファイルのいずれかが再生される。

[Play] ボタンが最初にクリックされたときと、オプション ボタンが選択されたときに、LoadSound プロシージャが呼び出される。このプロシージャが最初に行うのは、ファイルの存在の確認である。

    If Dir$(sFile) = vbNullString Then
        MsgBox "Unable to find " & sFile, vbOKOnly Or vbCritical, _
               "Not found."
        Unload Me
    End If

セグメントが既にロードされている場合は、シンセサイザからそのセグメントのバンドをアンロードしてから、セグメントを解放する。

    If Not (dmSeg Is Nothing) Then
        dmSeg.Unload dmPath
        Set dmSeg = Nothing
    End If

次に、新しいセグメントをロードする。セグメントが MIDI ファイルの場合、アプリケーションは DirectMusicSegment8.SetStandardMidiFile を呼び出す。標準的な MIDI ファイルは、DirectMusic Producer セグメントとして保存されているファイルといくぶん動作が異なるが、この呼び出しによって正しく処理することができる。

    Set dmSeg = dml.LoadSegment(sFile)
    If Right$(sFile, 4) = ".mid" Then dmSeg.SetStandardMidiFile

LoadSound プロシージャは、次の「ステップ 5 : バンドのダウンロード」に続く。


ステップ 5 : バンドのダウンロード

セグメントを再生するときに忘れやすいのが、バンドのダウンロードである。ウェーブ ファイルの場合、このステップは不要だが、実行しても問題は生じない。MIDI ファイルおよび DirectMusic Producer セグメントでは、このステップは必須である。これによって、シンセサイザは、正しいティンバーでノート メッセージを再生できる。

DirectMusicSegment8.Download メソッドは、オーディオパスまたはパフォーマンスをパラメータとして処理する。通常、アプリケーションで使用するシンセサイザは 1 つだけなので、どちらを使っても問題はない。サンプルでは、「ステップ 3 : オーディオパスの作成」で作成したオーディオパスにセグメントのバンドをダウンロードする。

dmSeg.Download dmPath

LoadSound プロシージャは、サウンドのボリュームと 3D 空間での位置を初期化して終了する。

    scrlPan_Change
    scrlVol_Change
End Sub

次の「ステップ 6 : オーディオパスでのサウンドの再生」に続く。


ステップ 6 : オーディオパスでのサウンドの再生

[Play] ボタンがクリックされると、次のプロシージャがオプション ボタンの状態を確認し、オプション ボタンの選択に応じて、まだロードされていないセグメントをロードする。次に、前のステップで作成したオーディオパスで、プライマリ セグメントとしてセグメントを再生する。

Private Sub cmdPlay_Click()

    If dmSeg Is Nothing Then
        If optWave.Value Then LoadSound MediaPath & "\tuta.wav"
        If optMid.Value Then LoadSound MediaPath & "\tut.mid"
        If optSeg.Value Then LoadSound MediaPath & "\sample.sgt"
    End If

    Set dmSegState = dmp.PlaySegmentEx(dmSeg, 0, 0, Nothing, dmPath)

End Sub

このプロシージャは、DirectMusicSegmentState8 オブジェクトを取得する。取得したオブジェクトは、再生状態に関する情報を取得するために使用される。セグメント状態を DirectMusicPerformance8.StopEx に渡してセグメントの 1 つのインスタンスだけを停止することもできる。この処理は、セカンダリ セグメントで有効である。セカンダリ セグメントは、同時に複数のインスタンスが再生されている場合がある。

次の「ステップ 7 : サウンドの停止」に続く。


ステップ 7 : サウンドの停止

次のプロシージャは、入力に応答してサウンドを停止する。サンプルのセグメントは繰り返しが設定されていないので、終端に到達したときには自動的に停止する。

Private Sub cmdStop_Click()
    If dmSeg Is Nothing Then Exit Sub
    dmp.StopEx dmSeg, 0, 0
    mlOffset = 0
End Sub

DirectMusicPerformance8.StopEx の呼び出しでは、セグメントを引数として処理する。前のステップで取得したセグメント状態やオーディオパスも処理できる。2 番目のパラメータは即時停止を指示する。3 番目のパラメータにはフラグは指定されない。フラグを使うと、小節の終わりなどの適切な境界に達してから音楽を停止するように要求できる。ただし、このような要求は、ウェーブ ファイルでは無視される。

次の「ステップ 8 : オーディオパス パラメータの設定」に続く。


ステップ 8 : オーディオパス パラメータの設定

サンプル アプリケーションでは、ユーザーは、いつでもスライダを移動することによってオーディオパスのボリュームを設定できる。これに応答して、アプリケーションは DirectMusicAudioPath8.SetVolume を呼び出す。変更は、そのオーディオパスで再生されるすべてのセグメントに影響する。アプリケーションに複数のオーディオパスが設定されている場合、ほかのオーディオパスで再生されるセグメントには影響しない。

Private Sub scrlVol_Change()
    dmPath.SetVolume scrlVol.Value, 0
End Sub

最初のパラメータは新しいボリュームである。1 デシベルの 100 分の 1 の単位で表される。サンプル アプリケーションでは、ボリュームを最大で 50 デシベル下げることができる。2 番目の値はフェード時間である。この時間を使ってボリュームは変更される。この場合、新しいボリュームが即座に設定される。

次の「ステップ 9 : 3D パラメータの設定」に続く。


ステップ 9 : 3D パラメータの設定

このステップでは、オーディオパスから DirectSound3DBuffer8 オブジェクトを取得して、それを使って空間内にサウンドを配置する方法を説明する。サンプル アプリケーションでパンできるのは左右方向だけだが、同じ手法を使って 3 次元空間内でサウンドを移動できる。

「ステップ 3 : オーディオパスの作成」では、パフォーマンスの初期化時に、アプリケーションは DMUS_APATH_DYNAMIC_3D 型のデフォルトのオーディオパスを要求した。この標準オーディオパスは、3D バッファを経由してデータを送信する。ユーザーがパン スライダを移動すると、アプリケーションは、まずこのバッファのオブジェクトを取得する。

Private Sub scrlPan_Change()
    If dmSeg Is Nothing Then Exit Sub

    Dim dsBuf As DirectSound3DBuffer8

    Set dsBuf = dmPath.GetObjectinPath(DMUS_PCHANNEL_ALL, _
        DMUS_PATH_BUFFER, 0, vbNullString, 0, _
        "IID_IDirectSound3DBuffer")

DirectMusicAudioPath8.GetObjectInPath のパラメータは、設定が少し複雑になっている。パス内の各段階のオブジェクトに対応したパラメータについては、「オーディオパスからのオブジェクトの取得」を参照すること。

チュートリアル サンプルでは、このオーディオパス上のすべてのパフォーマンス チャンネルで使用されるセカンダリ バッファを取得する。lPChannel パラメータを DMUS_PCHANNEL_ALL に設定する。

取得するのはチェーン内の 2 つのバッファの 1 つ目なので、lBuffer として 0 を渡す。DMUS_PATH_BUFFER ステージはバッファ オブジェクトだけを含み、それらのバッファに付加された DMO は含まない。このため、lIndex は無視される。

次に、アプリケーションでは、バッファ オブジェクトを使って音源の位置を設定する。

    dsBuf.SetPosition scrlPan.Value / 5, 0, 0, DS3D_IMMEDIATE
    Set dsBuf = Nothing

End Sub

最初の 3 つのパラメータは、音源の新しい位置をデフォルトのリスナーとの相対的な位置で指定する。デフォルトのリスナーは座標 (0.0, 0.0, 0.0) にあり、正面は z 軸の正の方向を向き、頭のてっぺんは y 軸の正の方向を向いている。デフォルトの距離の単位はメートルである。詳細については、「3D 空間の座標」および「リスナーの向き」を参照すること。

DirectSound3DBuffer8.SetPosition メソッドの最後のパラメータは、変更を直ちに適用するのか、すべての変更が行われてから適用するのかを指定する。詳細については、「遅延設定」を参照すること。


DirectX Audio Visual Basic サンプル

次のサンプル アプリケーションには、Microsoft® DirectX® for Visual Basic® での Microsoft® DirectMusic® および Microsoft® DirectSound® アプリケーション プログラミング インターフェイス (API) の使い方と機能が示されている。

各トピックで、次の 2 種類のサンプルについて説明する。

  • DirectMusic Visual Basic サンプル。これらのサンプルは、DirectMusic API を使ってサウンドをロードして再生している。一部のサンプルでは、DirectSound API 要素を使用している。
  • DirectSound Visual Basic サンプル。これらのサンプルは、DirectSound API のみを使用している。ただし、ここに示されるテクニックの多くは、DirectMusic オーディオパスから取得したバッファと共に使用することもできる。


DirectMusic Visual Basic サンプル

次に示す実行可能アプリケーションは、DirectMusic API のみまたは DirectSound と DirectMusic の両方を使用している。これらのアプリケーションを実行するには、[スタート] メニューの [プログラム] をポイントする。次に、[Microsoft DirectX8 SDK] をポイントし、[Visual Basic Samples] をポイントして、[DirectMusic Samples] をクリックする。

  • AudioEffects
  • AudioPath
  • DLSEffects
  • DMDrums
  • PlayAudio
  • PlayMotif
  • SimpleAudioPath

ソース コードは次のフォルダにある。

\mssdk\samples\Multimedia\VBSamples\DirectMusic\

これらのサンプルのほかに、次のフォルダに、チュートリアル アプリケーションのソース ファイルがある。

\mssdk\samples\Multimedia\VBSamples\DirectMusic\Tutorials

詳細については、「DirectX Audio Visual Basic チュートリアル」を参照すること。

注 DirectX SDK がインストールされているルート ディレクトリが異なる場合は、すべてのパスで "mssdk" をそのディレクトリの名前に置き換える必要がある。


AudioEffects

説明

AudioEffects サンプルは、オーディオパスからバッファを取得して、それにエフェクトを適用する方法を示す。DirectX に用意されている標準的なエフェクトも示す。

パス

ソース :(SDK ルート)\Samples\Multimedia\VBSamples\DirectMusic\AudioEffects

実行可能ファイル :(SDK ルート)\Samples\Multimedia\VBSamples\DirectMusic\Bin

ユーザーズ ガイド

サウンド ファイルをロードする。[Effects in Use] ボックスの一覧に 1 つまたは複数のエフェクトを追加する。エフェクトを追加するには、[Available Effects] ボックスの一覧のエフェクトを 1 つクリックして、右矢印をクリックする。エフェクトを削除するには、[Effects in Use] ボックスの一覧のエフェクトをクリックして、左矢印をクリックする。バッファのエフェクトを更新するには、[Apply Effects] をクリックする。

プログラミング メモ

cmdApply_Click プロシージャには、エフェクトを設定または削除するためのコードが含まれている。主なステップを次に示す。

  • DSEFFECTDESC 型の DSEffects 配列でエフェクトを記述する。
  • DirectMusicAudioPath8.GetObjectInPath を呼び出して、オーディオパスからバッファを取得する。
  • オーディオパスを非アクティブにする。
  • DirectSoundSecondaryBuffer8.SetFX を呼び出してエフェクトを設定する。
  • オーディオパスを再びアクティブにする。


AudioPath

説明

AudioPath サンプルは、個別のオーディオパスでファイルを再生する方法を示す。各オーディオパスは、個別に操作できる。

パス

ソース :(SDK ルート)\Samples\Multimedia\VBSamples\DirectMusic\AudioPath

実行可能ファイル :(SDK ルート)\Samples\Multimedia\VBSamples\DirectMusic\Bin

ユーザーズ ガイド

Audiopath 1 に 1 つのファイルをロードして、Audiopaths 2 および Audiopath 3 に 1 つまたは複数のファイルをロードする。各オーディオパスの [Play] をクリックすると、そのパスのすべてのファイルが再生される。同時に複数のオーディオパスを再生できる。スライダを使うと、各オーディオパスのボリュームと3D 空間の広がりを変更できる。

プログラミング メモ

InitAudio プロシージャは、デフォルトのオーディオパスを使わずにパフォーマンスを初期化し、3 つの標準オーディオパスを作成する。各セグメントを特定のオーディオパスで再生するには、そのオーディオパスを DirectMusicPerformance8.PlaySegmentEx に渡す。

1 つのセグメントの複数のインスタンスを 1 つのオーディイパスで再生することができる。これには、1 つのファイルをセカンダリ セグメントとして複数回ロードする。サンプルでは、複数のインスタンスが同時に再生されるので、実際には 1 つしか聞こえない。ただし、サンプルは、DirectMusicSegmentState8 オブジェクトが各インスタンスをどのように表しているかを示している。このオブジェクトは、インスタンスが再生中であるかどうかを確認するために DirectMusicPerformance8.IsPlaying に渡される。


DLSEffects

説明

DLSEffects サンプルは、アプリケーションでサウンド エフェクトに DLS 音色を使う方法と、MIDI メッセージを送信する方法を示す。

パス

ソース :(SDK ルート)\Samples\Multimedia\VBSamples\DirectMusic\DLSEffects

実行可能ファイル :(SDK ルート)\Samples\Multimedia\VBSamples\DirectMusic\Bin

ユーザーズ ガイド

[C3] ボタンと [C10] ボタンをクリックしてボーカル エフェクトを再生する。[On] をクリックすると、ハートビート エフェクトが同時に再生される。[Note] スライダと [Pitch Bend] スライダを使うとピッチを変更できる。右のスライダを使ってノートのベロシティ (ボリューム) を設定する。ベロシティの変更は、変更後に開始されたサウンドだけに適用される。

プログラミング メモ

DLS 音色は、Boids.dls から取得する。このコレクションには、Vocals と呼ばれる 1 つの音色だけが含まれている。この音色は、異なるリージョンの異なるウェーブ サンプルまたはノート範囲に基づいている。たとえば、C3 と B3 の間の MIDI ノートを再生すると、最初の話し声のサウンドが使用される。話し声のサウンドが元のピッチで再生されるのは、リージョン内で一番低いノートの場合だけである。

サンプルの 1 つは、ハートビートと呼ばれ、B7 ～ B8 の範囲で有効である。これは話し声のサンプルではないので、ピッチをある程度変更できる。ピッチを変更するには、スライダの設定を変更して、範囲内のさまざまなノートを演奏する。

また、ハートビートは、DLS コレクションの中で、ループ サウンドに基づく唯一のサンプルである。このため、ノートが演奏されている間、連続して再生できる。ほかのサンプルは、ノートの長さに関係なく、再生は 1 回だけである。


DMDrums

説明

DMDrums サンプル アプリケーションは、バンド、マスタ グルーブ レベル、およびテンポを変更して音楽を変化させる方法を示す。また、ユーザーの入力に応答してモチーフを再生する方法も示す。

パス

ソース :(SDK ルート)\Samples\Multimedia\VBSamples\DirectMusic\DMDrums

実行可能ファイル :(SDK ルート)\Samples\Multimedia\VBSamples\DirectMusic\Bin

ユーザーズ ガイド

[Play] ボタンをクリックして音楽を開始する。[Groove] ボックスの一覧から異なる種類の音楽を選択して、[Drum Sets] ボックスの一覧から異なるバンドを選択する。UpDown コントロールでテンポとボリュームを調整する。ドラム ボタンのいずれかをクリックして、ドラム モチーフを再生する。

プログラミング メモ

[Groove] ボックスでの選択によってマスタ グルーブ レベルが決まり、セグメントに関連するスタイル オブジェクトから異なるパターンが選択される。

ドラム ボタンをクリックするたびに異なるモチーフが再生される。ボタンに関連付けられている音色がモチーフに割り当てられる。


PlayAudio

説明

PlayAudio サンプルは、オーディオパスでサウンドを再生する。このサンプルでは、ユーザーがテンポおよびマスタ ボリュームを設定できる。

パス

ソース :(SDK ルート)\Samples\Multimedia\VBSamples\DirectMusic\PlayAudio

実行可能ファイル :(SDK ルート)\Samples\Multimedia\VBSamples\DirectMusic\Bin

ユーザーズ ガイド

[Audio File] をクリックして、セグメント、MIDI ファイル、またはウェーブをロードする。再生オプションを選択する。ウェーブ ファイルでは、[Tempo] スライダは無効である。

プログラミング メモ

アプリケーションは DMUS_NOTIFY_ON_SEGMENT 型の通知を設定して、この通知により、イベント関連のさまざまなイベントに対するプロシージャをトリガする。コールバック プロシージャで、通知メッセージのサブタイプを確認して、セグメントの再生が停止されたかどうかを調べる。既に停止されている場合は、ユーザー インターフェイスが更新されて再生オプションが有効になる。


PlayMotif

説明

PlayMotif サンプルは、セカンダリ セグメントとして再生されるモチーフをプライマリ セグメントのリズムに割り当てるさまざまな方法を示す。

パス

ソース :(SDK ルート)\Samples\Multimedia\VBSamples\DirectMusic\PlayMotif

実行可能ファイル :(SDK ルート)\Samples\Multimedia\VBSamples\DirectMusic\Bin

ユーザーズ ガイド

デフォルトのセグメントを再生するか、モチーフを含む別の DirectMusic Producer セグメントをロードする。リスト ボックスからパターンを 1 つ選択し、[Align Option] ボタンを 1 つ選択して、[Play Motif] をクリックする。プライマリ セグメントの適切な境界に到達するまで、モチーフの再生は開始されない。

プログラミング メモ

モチーフに関する情報は、ユーザー定義の配列に含まれ、LoadSegment プロシージャで初期化される。モチーフを再生するとき、モチーフはプライマリ セグメントのリズムに揃えられる。この処理は、cmdPlayMotif_Click プロシージャで、CONST_DMUS_SEGF_FLAGS の 1 つを DirectMusicPerformance8.PlaySegmentEx に渡すことによって行われる。

ユーザー インターフェイスは、通知を使って常に最新の状態に保たれる。注目すべきなのは、DMUS_NOTIFICATION_PMSG 型の User メンバからセグメント状態を取得する方法である。アプリケーションは、セグメント状態を取得して、モチーフの開始または停止を確認する。


SimpleAudioPath

説明

SimpleAudioPath サンプルは、1 つのオーディオパスで複数の異なるサウンドを再生する方法と、オーディオパスでの変更がすべてのサウンドのパラメータに与える影響を示す。

パス

ソース :(SDK ルート)\Samples\Multimedia\VBSamples\DirectMusic\SimpleAudioPath

実行可能ファイル :(SDK ルート)\Samples\Multimedia\VBSamples\DirectMusic\Bin

ユーザーズ ガイド

[Lullaby]、[Snore]、および [Mumble] をクリックしてさまざまなサウンドを再生する。スライダを使って、3D 空間でのサウンドの位置を調整する。[Rude Awakening] をクリックすると、ほかのすべてのサウンドが停止される。

プログラミング メモ

プライマリ セグメントとして子守歌が再生される。つまり、この子守歌のインスタンスが同時に複数再生されることはない。いびきと寝言のサウンドのインスタンスは複数再生できる。

オーディオパスのタイプは DMUS_APATH_DYNAMIC_3D である。このパスには 3D バッファが含まれ、すべてのサウンドはシンセサイザによって合成されてこのバッファに格納される。サウンドの位置を変更するには、アプリケーションは、オーディオパスから DirectSound3DBuffer8 オブジェクトを取得して、DirectSound3DBuffer8.SetPosition を呼び出す。

[Rude Awakening] がクリックされると、オーディオパスが From パラメータとして DirectMusicPerformance8.PlaySegmentEx に渡される。これによって、そのオーディオパスで再生中のすべてのセグメントを停止してから、新しいセグメントが開始される。


DirectSound Visual Basic サンプル

次に示す実行可能アプリケーションは DirectSound のみを使用している。これらのアプリケーションを実行するには、[スタート] メニューの [プログラム] をポイントする。次に、[Microsoft DirectX8 SDK] をポイントし、[Visual Basic Samples] をポイントして、[DirectSound Samples] をクリックする。

  • AdjustSound
  • DeferredEffects
  • EffectsBuffers
  • EnumDevice
  • Play3DSound

これらのサンプルのソース コードは次のフォルダにある。

\mssdk\samples\Multimedia\VBSamples\DirectSound\

これらのサンプルのほかに、次のフォルダに、チュートリアル アプリケーションのソース ファイルがある。

\mssdk\samples\Multimedia\VBSamples\DirectSound\Tutorials

詳細については、「DirectX Audio Visual Basic チュートリアル」を参照すること。

注 : DirectX SDK がインストールされているルート ディレクトリが異なる場合は、すべてのパスで "mssdk" をそのディレクトリの名前に置き換える必要がある。


AdjustSound

説明

AdjustSound サンプルは、DirectSound セカンダリ バッファを作成してウェーブ ファイルを再生する方法と、バッファのパラメータを変更する方法を示す。

パス

ソース :(SDK ルート)\Samples\Multimedia\VBSamples\DirectSound\AdjustSound

実行可能ファイル :(SDK ルート)\Samples\Multimedia\VBSamples\DirectSound\Bin

ユーザーズ ガイド

[Sound File] をクリックしてウェーブ ファイルをロードする。[Focus] オプションおよび [Buffer Mixing] オプションを選択する。オプションの選択に応じて、さまざまな設定が [Expected Behavior] に表示される。[Play] をクリックする。何もサウンドが聞こえない場合は、[Status] ペインを確認する。このオプションが選択されていないと、アプリケーションがハードウェアにバッファを作成できない場合がある。

バッファの再生中に、スライダを使って周波数、パン、およびボリュームを動的に調整できる。

プログラミング メモ

アプリケーションは、ファイルのロード時、および [Play] がクリックされるたびに、そのときに選択されているオプションを使用してサウンド バッファの作成を試みる。


DeferredEffects

説明

DefferedEffects サンプルは、エフェクトを含む遅延サウンド バッファを作成する方法を示す。リソースは、アプリケーションによって要求されてから、バッファに割り当てられる。

パス

ソース :(SDK ルート)\Samples\Multimedia\VBSamples\DirectSound\DeferredEffects

実行可能ファイル :(SDK ルート)\Samples\Multimedia\VBSamples\DirectSound\Bin

ユーザーズ ガイド

上のテキスト ボックスの横にあるボタンをクリックしてウェーブをロードする。上のボックスの一覧のエフェクトをクリックして下矢印をクリックするか、エフェクトをダブルクリックして、下のボックスに移動する。エフェクトを削除するには、下のボックスの一覧のエフェクトをクリックして上矢印をクリックするか、エフェクトをダブルクリックする。バッファのエフェクトを更新するには、[Apply Effects] をクリックする。各エフェクトのステータスが [Effects in Use] ボックスに表示される。サウンドを再生する。

プログラミング メモ

作成されるサウンド バッファには DSBCAPS_LOCDEFER フラグが指定されている。このため、リソースは、それが再生されるか、アプリケーションによって DirectSoundSecondaryBuffer8.AcquireResources が呼び出されるまでバッファに割り当てられない。

DirectSoundSecondaryBuffer8.SetFX が呼び出されたときも、バッファは遅延する。この場合、アプリケーションは、直ちに AcquireResources を呼び出してリソースをバッファに割り当てる。その後、エフェクトが正常に初期化されたかをどうかと、エフェクトがハードウェアに配置されているのかソフトウェアに配置されているのかを確認する (DirectX 8.0 では、すべてのエフェクトはソフトウェアに配置される)。


EffectsBuffers

説明

EffectsBuffers サンプルは、DirectSound セカンダリ バッファでのエフェクトの使い方と、エフェクトのパラメータを変更する方法を示す。

パス

ソース :(SDK ルート)\Samples\Multimedia\VBSamples\DirectSound\EffectsBuffers

実行可能ファイル :(SDK ルート)\Samples\Multimedia\VBSamples\DirectSound\Bin

ユーザーズ ガイド

上のテキスト ボックスの横にあるボタンをクリックしてウェーブをロードする。上のボックスの一覧のエフェクトをクリックして下矢印をクリックするか、エフェクトをダブルクリックして、下のボックスに移動する。エフェクトを削除するには、下のボックスの一覧のエフェクトをクリックして上矢印をクリックするか、エフェクトをダブルクリックする。エフェクトを右クリックし、ポップアップ メニューの [Remove] をクリックしてエフェクトを削除することもできる。バッファのエフェクトを更新するには、[Apply Effects] をクリックする。各エフェクトのステータスが [Effects in Use] ボックスに表示される。サウンドを再生する。

サウンドが再生されていないときに、エフェクトのパラメータを変更できる。[Effects In Use] ボックスの一覧のエフェクトをクリックして [Modify Effect] をクリックするか、エフェクトを右クリックしてポップアップ メニューの [Change Settings] をクリックする。

プログラミング メモ

ApplySettings 関数は、エフェクトの組み合わせごとに一意の値を作成することによって、適用済みのエフェクトを追跡する。[Apply Effects] をクリックすると、現在の組み合せが、mlEffectKey に保存されている前の組み合せと比較されて、エフェクトが更新されているかどうかが確認される。


EnumDevice

説明

EnumDevice サンプルは、再生デバイスとキャプチャ デバイスを列挙および作成する方法を示す。

パス

ソース :(SDK ルート)\Samples\Multimedia\VBSamples\DirectSound\EnumDevice

実行可能ファイル :(SDK ルート)\Samples\Multimedia\VBSamples\DirectSound\Bin

ユーザーズ ガイド

ドロップダウン リストから再生デバイスとキャプチャ デバイスを選択する。[Create] をクリックする。

プログラミング メモ

LoadEnum プロシージャは、リスト ボックスを配置する。システムのプライマリ デバイスは常に 2 回列挙される。1 回は正式な名前で列挙され、もう 1 回は "プライマリ サウンド ドライバ" または "プライマリ サウンド キャプチャ ドライバ" として列挙される。プライマリ デバイスに対して DirectSoundEnum8.GetGuid から返される値は、すべて 0 である。

DirectSound8 オブジェクトは、作成されると直ちに解放される。全二重をサポートしていないシステムでは、DirectSound8 が存在すると DirectSoundCapture8 が失敗する場合がある。


Play3DSound

説明

Play3DSound サンプルは、3D サウンド バッファを作成する方法と、そのプロパティを操作する方法を示す。

パス

ソース :(SDK ルート)\Samples\Multimedia\VBSamples\DirectSound\Play3DSound

実行可能ファイル :(SDK ルート)\Samples\Multimedia\VBSamples\DirectSound\Bin

ユーザーズ ガイド

[Sound] をクリックしてモノ ウェーブ ファイルをロードする。3D 仮想化アルゴリズムを選択する。サウンドを再生し、スライダを使って音源のボリュームと方向を設定する。方向は、サウンド コーンの向きである。サウンド コーンは、赤い三角形の狭い角の方を向いている。音源を移動するには、赤い三角形をドラッグするか、移動先をクリックする。リスナーは黒い三角形で表されており、これは移動できない。

プログラミング メモ

2 次元表示の限界により、音源の移動は、x 軸 (画面の右が正の方向) の方向と z 軸 (画面の下が正の方向) の方向に制限される。アプリケーションは、リスナーのデフォルトの位置 (0, 0, 0) と向き (0, 0, 1) を使用する。つまり、リスナーは画面の上を向いている。

ユーザーがステレオ ファイルのロードを試みると、エラーが発生する。これは、DSBCAPS_CTRL3D フラグを指定してステレオ ウェーブ フォーマットのバッファを作成することができないためである。DirectSound8.CreateSoundBufferFromFile に渡された DSBUFFERDESC 型は、メソッドが失敗してもフォーマットに関する情報を受信する。アプリケーションは、これを利用して、エラーを処理した後に警告を出力する。バッファは、メソッドが成功しても破棄される。これは、ユーザーの希望する仮想化アルゴリズムを確認した後に、アプリケーションによって新しいバッファが作成されるためである。この新しいバッファから取得した DirectSound3DBuffer8 オブジェクトが、3D パラメータの制御に使用される。


DirectMusic Visual Basic リファレンス

ここでは、Microsoft® DirectMusic® for Microsoft® Visual Basic® の API 要素に関するリファレンス情報を記述する。リファレンス情報は以下のカテゴリに分類される。

  • DirectMusic クラス
  • DirectMusic 型
  • DirectMusic 列挙型
  • DirectMusic エラー コード


DirectMusic クラス

ここでは、以下の DirectMusic クラスのメソッドに関するリファレンスを提供する。

  • DirectMusicAudioPath8
  • DirectMusicBand8
  • DirectMusicChordMap8
  • DirectMusicCollection8
  • DirectMusicComposer8
  • DirectMusicLoader8
  • DirectMusicPerformance8
  • DirectMusicSegment8
  • DirectMusicSegmentState8
  • DirectMusicStyle8


DirectMusicAudioPath8

パフォーマンスから DirectSound バッファへのデータ フローのステージを表す。標準オーディオパスは、DirectMusicPerformance8.CreateStandardAudioPath を使って作成できる。また、標準のデフォルト パスは、DirectMusicPerformance8.InitAudio で作成でき、DirectMusicPerformance8.GetDefaultAudioPath で取得できる。最後に、オーディオパスは、DirectMusicPerformance8.CreateAudioPath メソッドを使って、セグメントのオーディオパス構成から作成できる。

DirectMusicAudioPath8 オブジェクトを DirectMusicPerformance8.PlaySegmentEx に渡すと、そのオーディオパス上のセグメントが演奏される。

DirectMusicAudioPath8 クラスは、以下のグループにまとめることができる。

DirectMusicAudioPath8 | Activate
 | GetObjectInPath
 | SetVolume


DirectMusicAudioPath8.Activate

オーディオパスをアクティブまたは非アクティブにする。

object.Activate(fActive As Boolean)

指定項目

object
DirectMusicAudioPath8 オブジェクトを指定する。
fActive
パスの状態を指定する Boolean 値。TRUE でパスをアクティブにし、FALSE でパスを非アクティブにする。

エラー コード

失敗した場合は、エラーが発生する。


DirectMusicAudioPath8.GetObjectInPath

オーディオパス内のオブジェクトを取得する。

object.GetObjectInPath( _
  lPChannel As Long, _
  lStage As CONST_DMUSIC_PATH, _
  lBuffer As Long,
  guidObject As String, _
  lIndex As Long, _
  iidInterface As String _
) As Unknown

指定項目

object
DirectMusicAudioPath8 オブジェクトを指定する。
lPChannel
検索するパフォーマンス チャンネル。DMUS_PCHANNEL_ALL を指定すると、すべてのチャンネルが検索される。最初のチャンネルは 0 番になる。「注意」を参照すること。
lStage
パス内のステージ。CONST_DMUSIC_PATH 列挙型のいずれかの定数である。「注意」を参照すること。
lBuffer
lStage が DMUS_PATH_BUFFER_DMO または DMUS_PATH_MIXIN_BUFFER_DMO である場合、DMO が存在するバッファのインデックスを指定する。lStage が DMUS_PATH_BUFFER または DMUS_PATH_MIXIN_BUFFER である場合、バッファのインデックスを指定する。それ以外の場合は、0 を指定する。
guidObject
CLSID_DirectMusicPerformance など、オブジェクトのクラス識別子。GUID_ALL_OBJECTS を指定すると、任意のクラスが検索される。lStage によって指定されたステージに存在するオブジェクトが単一のクラスに限定されている場合は無視される。このパラメータは GUID_NULL に設定できる。
lIndex
一致するオブジェクトのリストに含まれるオブジェクトのインデックス。0 に設定して、最初の適合オブジェクトを検索する。lStage が DMUS_PATH_BUFFER または DMUS_PATH_MIXIN_BUFFER の場合、このパラメータは無視され、lBuffer によってバッファ インデックスが指定される。
iidInterface
必要なクラスの識別子。文字列形式の GUID、または IID_DirectSoundPrimaryBuffer など、AUDIOSTRINGCONSTANTS モジュール内の識別子の 1 つ。

戻り値

iidInterface に指定されたクラスのオブジェクトを返す。

エラー コード

失敗した場合は、エラーが発生する。Err.Number には次のいずれかの値が設定される。

DMUS_E_NOT_FOUND
DMUS_E_NOINTERFACE

注意

チャンネル固有でないステージについては、lPChannel の値は 0 に設定しなければならない。次のステージのオブジェクトはチャンネル固有なので、lPChannel にチャンネル番号または DMUS_PCHANNEL_ALL を設定して取得できる。

DMUS_PATH_AUDIOPATH_TOOL
DMUS_PATH_BUFFER
DMUS_PATH_BUFFER_DMO
DMUS_PATH_PERFORMANCE_TOOL
DMUS_PATH_PORT
DMUS_PATH_SEGMENT_TOOL

不必要なオブジェクトをフィルタリングによって除外するときのパラメータの優先順位は次のとおりである。

  1. lStage。
  2. guidObject。この値が GUID_All_Objects でない場合、クラス識別子が guidObject に等しいオブジェクトだけが検索される。ただし、指定されたステージのオブジェクトのクラスが 1 つに限定されている場合、このパラメータは無視される。
  3. lPChannel。ステージがチャンネル固有で、この値が DMUS_PCHANNEL_ALL でない場合、そのチャンネルのオブジェクトだけが検索される。
  4. lBuffer。このパラメータが使用されるのは、lStage が DMUS_PATH_BUFFER、DMUS_PATH_MIXIN_BUFFER、DMUS_PATH_BUFFER_DMO、または DMUS_PATH_MIXIN_BUFFER_DMO の場合だけである。
  5. lIndex。

一致するオブジェクトが見つかっても、iidInterface で指定されているクラスが見つからない場合は、このメソッドは失敗する。

このメソッドで取得できるオブジェクトのタイプの中には、DirectX for Visual Basic でサポートされていないものもある。たとえば、lStage に DMUS_PATH_PERFORMANCE_TOOL を設定しても、ツールがサポートされていないので無意味である。

参照

オーディオパスからのオブジェクトの取得


DirectMusicAudioPath8.SetVolume

パスのオーディオ ボリュームを設定する。

object.SetVolume(lVolume As Long, lDuration As Long)

指定項目

object
DirectMusicAudioPath8 オブジェクトを指定する。
lVolume
減衰を指定する値。1/100 デシベル単位で指定する。
lDuration
どのぐらいの時間が経過すればボリューム変更が発生するかを指定する値。ミリ秒単位で指定する。この値に 0 を指定すると、即時実行が保証される。

エラー コード

失敗した場合は、エラーが発生する。


DirectMusicBand8

バンドを表す。バンドを使って、一連のパフォーマンス チャンネルの音色の選択肢とミキサ設定を指定する。

バンドは専用のファイルに直接保存しても、スタイルに埋め込んでもよい。DirectMusicBand8 オブジェクトは、次のいずれかのメソッドを使って取得する。

  • DirectMusicLoader8.LoadBand
  • DirectMusicLoader8.LoadBandFromResource
  • DirectMusicStyle8.GetDefaultBand
  • DirectMusicStyle8.GetBand

DirectMusicBand8 クラスは、以下のグループにまとめることができる。

セグメント作成 | CreateSegment
音色データ | Download
 | Unload


DirectMusicBand8.CreateSegment

DirectMusicPerformance8.PlaySegmentEx メソッドを使って、セグメント オブジェクトを作成する。このオブジェクトを使って、バンド内でのボリューム、パン、転調、およびパッチ チェンジ コマンドを動的に実行できる。

object.CreateSegment() As DirectMusicSegment8

指定項目

object
DirectMusicBand8 オブジェクトを指定する。

戻り値

DirectMusicSegment8 オブジェクトを返す。

エラー コード

失敗した場合は、Err.Number に次のいずれかの値が設定される。

DMUS_E_FAIL
DMUS_E_OUTOFMEMORY


DirectMusicBand8.Download

バンド内の音色の DLS データをパフォーマンス オブジェクトにダウンロードする。バンドのダウンロードが終わると、そのバンド内の音色は、プログラム チェンジ MIDI メッセージにより個別に選択するか、DirectMusicBand8.CreateSegment メソッドを呼び出して作成したバンド セグメントを演奏することにより一度にすべてを選択できる。

object.Download(downloadpath As Unknown)

指定項目

object
DirectMusicBand8 オブジェクトを指定する。
downloadpath
どのパスでバンドを実行するかを指定する DirectMusicAudioPath8 オブジェクトか DirectMusicPerformance8 オブジェクト。

エラー コード

失敗した場合は、Err.Number に次のいずれかの値が設定される。

DMUS_E_NOT_INIT
DMUS_E_OUTOFMEMORY

注意

ダウンロードされたバンドはシンセサイザ リソースを使用するため、不要になったときは、DirectMusicBand8.Unload メソッドを使ってアンロードしなければならない。

DMUS_E_NOT_INIT が返された場合は、通常、初期化されたポートにパフォーマンスが正常に接続されなかったことを意味する。これは完全な失敗であるため、後で DirectMusicBand8.Unload を呼び出す必要はない。

ダウンロードが部分的に成功する場合、エラーは返されないが、一部の音色が演奏されない場合がある。部分的なダウンロードが発生する一般的な原因を以下に示す。

  • バンドは、ポートに割り当てられていないパフォーマンス チャンネル上に音色を保持する。
  • バンドは、音色のダウンロード先となるシンセサイザと互換性のない DLS フォーマットの音色を持っている。


DirectMusicBand8.Unload

DirectMusicBand8.Download によって前にダウンロードされたバンド内の音色の DLS データをアンロードする。

object.Unload(downloadpath As Unknown)

指定項目

object
DirectMusicBand8 オブジェクトを指定する。
downloadpath
どのパスにバンドをダウンロードするかを指定する DirectMusicAudioPath8 オブジェクトか DirectMusicPerformance8 オブジェクト。

エラー コード

失敗するとエラーが発生する。Err.Number には次のいずれかの値が設定される。

DMUS_E_NOT_INIT
DMUS_E_NOT_FOUND


DirectMusicChordMap8

コード マップを表す。コード マップは、DirectMusicComposer8 に対し、アレンジするセグメントのコード進行を作成するのに必要な情報を提供する。コード マップを既存のセグメントに適用して、コードを変更することもできる。

このクラスには、パブリック メソッドがない。このクラスのインスタンスは、DirectMusicPerformance8.GetChordmap メソッドを使って取得する。

参照

DirectMusicComposer8.AutoTransition、DirectMusicComposer8.ChangeChordMap、DirectMusicComposer8.ComposeSegmentFromShape、DirectMusicComposer8.ComposeSegmentFromTemplate、DirectMusicComposer8.ComposeTransition、DirectMusicPerformance8.GetChordmap


DirectMusicCollection8

DLS ファイルのインスタンスを管理する。

このクラスには、パブリック メソッドがない。このクラスのインスタンスは、DirectMusicLoader8.LoadCollection メソッドまたは DirectMusicLoader8.LoadCollectionFromResource メソッドを使って取得し、DirectMusicSegment8.ConnectToCollection を呼び出すことによってセグメントに関連付ける。


DirectMusicComposer8

アレンジ要素からセグメントとトランジションをアレンジし、既存セグメントのコード マップを変更するために使われる。

DirectMusicComposer8 オブジェクトは、DirectX8.DirectMusicComposerCreate メソッドを使って取得する。

DirectMusicComposer8 クラスのメソッドは、以下のグループにまとめることができる。

コード マップの変更 | ChangeChordMap
通常のセグメントのアレンジ | ComposeSegmentFromShape
 | ComposeSegmentFromTemplate
テンプレート セグメントのアレンジ | ComposeTemplateFromShape
トランジション セグメントのアレンジ | AutoTransition
 | ComposeTransition


DirectMusicComposer8.AutoTransition

パフォーマンスのプライマリ セグメント (または無音) 内部からほかのセグメントへのトランジションをアレンジし、演奏の目的でそのトランジションとセカンダリ セグメントを挿入する。

object.AutoTransition( _
    performance As DirectMusicPerformance8, _
    toSeg As DirectMusicSegment8, _
    lCommand As Long, _
    lFlags As Long, _
    chordmap As DirectMusicChordMap8 _
) As DirectMusicSegment8

指定項目

object
DirectMusicComposer8 オブジェクトを指定する。
performance
トランジションに関係する DirectMusicPerformance8 オブジェクト。
toSeg
移行先セクション。トランジションはこのセクションへ円滑に移行する。「注意」を参照すること。
lCommand
トランジションを作成するときに使われる装飾。「CONST_DMUS_COMMANDT_TYPES」を参照すること。この値が DMUS_COMMANDT_ENDANDINTRO の場合、メソッドは、プライマリ セグメントのエンディングと toSeg のイントロを含むセグメントをアレンジする。
lFlags
コンポーザ オプション。「CONST_DMUS_COMPOSEF_FLAGS」を参照すること。
chordmap
トランジションをアレンジするときに使用する DirectMusicChordMap8 オブジェクト。

戻り値

トランジション セグメントのアレンジに利用できるスタイルがほかにない場合に限り、DirectMusicSegment8 オブジェクトを返す。「注意」を参照すること。

エラー コード

失敗した場合はエラーが発生し、Err.Number が設定される。

注意

lFlags が DMUS_COMPOSEF_MODULATE を含んでいない場合、toSeg の値は NULL でもよい。toSeg が NULL またはスタイル トラックを含まないセグメントの場合、イントロの装飾は無効になる。演奏中のセグメントがない場合またはセグメントがスタイル トラックを含んでいない場合は、フィル、ブレーク、エンド、およびグルーブの装飾が無効になる。

演奏中のセグメントまたは segment1 のどちらも、NULL またはスタイル トラックを含まないセグメント (MIDI ファイルに基づくセグメントなど) を指定できる。その場合、すべての装飾は無効になり、演奏中のセグメントと segment1 の間でトランジションは行われない。メソッドは NULL を返すが、成功して、segment1 によって表されるセグメントを挿入する。

chordmap の値は NULL でもよい。値が NULL の場合、コード マップ トラックからコード マップを取得する試みが行われる。最初に segment1、次にパフォーマンスのプライマリ セグメントが試される。どのセグメントにもコード マップ トラックが含まれない場合は、現在のタイムにプライマリ セグメント内で発生するコードがトランジションのコードとして使われる。


DirectMusicComposer8.ChangeChordMap

新しいコード マップを反映して、既存セグメントのコードとスケール パターンを変更する。

object.ChangeChordMap(segment As DirectMusicSegment8, _
    trackScale As Boolean, _
    chordmap As DirectMusicChordMap8)

指定項目

object
DirectMusicComposer8 オブジェクトを指定する。
segment
コード マップを変更するセグメントを指定する DirectMusicSegment8 オブジェクト。
trackScale
スケール トラッキングを指定する Boolean 型の値。TRUE の場合、メソッドは、すべてのコードを新しいコード マップ スケールのルート音に相対的に転置する。FALSE の場合、ルート音はそのまま残される。
chordmap
セグメントに適用する新しいコードマップを指定する DirectMusicChordMap8 オブジェクト。

エラー コード

失敗した場合はエラーが発生し、Err.Number が設定される。

注意

メソッドはセグメントの演奏中に呼び出すことができる。


DirectMusicComposer8.ComposeSegmentFromShape

あらかじめ定義されたシェイプに基づいて、スタイルとコード マップからオリジナルのセクション セグメントを作成する。このシェイプは、セクション全体で時間の経過に伴ってコードと装飾を発生させる方法を表す。

object.ComposeSegmentFromShape(style As DirectMusicStyle8, _
    numberOfMeasures As Integer, _
    shape As Integer, _
    activity As Integer, _
    bIntro As Boolean, _
    bEnd As Boolean, _
    chordmap As DirectMusicChordMap8 _
) As DirectMusicSegment8

指定項目

object
DirectMusicComposer8 オブジェクトを指定する。
style
セクション セグメントのアレンジに使うスタイルを指定する DirectMusicStyle8 オブジェクト。
numberOfMeasures
アレンジするセクション セグメントの長さ。小節単位で指定する。
shape
アレンジするセクション セグメントのシェイプ。グルーブ レベルの変更に基づく。CONST_DMUS_SHAPET_TYPES 列挙型のいずれかを指定する。
activity
和音進行のレート。有効な値は 0 ～ 3。値が低いと、コード チェンジが増える。
bIntro
テンプレート セグメントのイントロをアレンジしたい場合は TRUE。それ以外の場合は FALSE。
bEnd
テンプレート セグメントのエンディングをアレンジしたい場合は TRUE。それ以外の場合は FALSE。
chordmap
セクション セグメントの作成に使用する DirectMusicChordMap8 オブジェクト。

戻り値

DirectMusicSegment8 オブジェクトを返す。

エラー コード

失敗した場合はエラーが発生し、Err.Number が設定される。

参照

DirectMusicComposer8.ComposeSegmentFromTemplate、DirectMusicComposer8.ComposeTemplateFromShape


DirectMusicComposer8.ComposeSegmentFromTemplate

スタイル、コード マップ、およびテンプレートからオリジナルのセクション セグメントを作成する。

object.ComposeSegmentFromTemplate( _
    style As DirectMusicStyle8, _
    templateSeg As DirectMusicSegment8, _
    activity As Integer, _
    chordmap As DirectMusicChordMap8 _
) As DirectMusicSegment8

指定項目

object
DirectMusicComposer8 オブジェクトを指定する。
style
セクション セグメントの作成に使用する DirectMusicStyle8 オブジェクト。
templateSeg
セクション セグメントの作成に使用するテンプレートを表す DirectMusicSegment8 オブジェクト。
activity
和音進行のレート。有効な値は 0 ～ 3。値が低いと、コード チェンジが増える。
chordmap
セクション セグメントの作成に使用するコード マップを表す DirectMusicChordMap8 オブジェクト。

戻り値

DirectMusicSegment8 オブジェクトを返す。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

DMUS_E_INVALIDARG

注意

style が NULL ではない場合、このスタイルはセグメントのアレンジに使用される。NULL の場合、templateSeg で指定されたテンプレートから取得したスタイルをセグメントのアレンジに使用する。同様に、chordmap が NULL ではない場合、このコード マップはセグメントのアレンジに使用される。NULL の場合、テンプレートから取得したコード マップをセグメントのアレンジに使用する。

style が NULL でテンプレート内にスタイル トラックが存在しない場合や、chordmap が NULL でコード マップ トラックが存在しない場合、このメソッドは DMUS_E_INVALIDARG を返す。

セクション セグメントの長さは、渡されたテンプレート セクションの長さと等しくなる。

参照

DirectMusicComposer8.ComposeSegmentFromShape、DirectMusicComposer8.ComposeTemplateFromShape


DirectMusicComposer8.ComposeTemplateFromShape

あらかじめ定義されたシェイプに基づいて新しいテンプレートを作成する。

object.ComposeTemplateFromShape(numMeasures As Integer, _
    shape As Integer, _
    bIntro As Boolean, _
    bEnd As Boolean, _
    endLength As Integer _
) As DirectMusicSegment8

指定項目

object
DirectMusicComposer8 オブジェクトを指定する。
numMeasures
アレンジするセクション セグメントの長さ。小節単位で指定する。0 より大きい値でなければならない。
shape
アレンジするテンプレート セグメントのシェイプ。グルーブ レベルに基づく。CONST_DMUS_SHAPET_TYPES 列挙型のいずれかを指定する。
bIntro
テンプレート セグメントのイントロをアレンジしたい場合は TRUE。それ以外の場合は FALSE。
bEnd
テンプレート セグメントのエンディングをアレンジしたい場合は TRUE。それ以外の場合は FALSE。
endLength
エンディングを作成したい場合は、エンディングの長さ。小節単位で指定する。bEnd が TRUE の場合、この値は 0 より大きく、利用できる小節数以下でなければならない (つまり、イントロで使われない)。「注意」も参照すること。

戻り値

DirectMusicSegment8 オブジェクトを返す。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

DMUS_E_INVALIDARG
DMUS_E_OUTOFMEMORY

注意

endLength の値は、DirectMusicComposer8.ComposeSegmentFromTemplate メソッドを使ってこのテンプレートに関連付けられる可能性のある任意のスタイル内で利用できる最長のエンディングの長さを超えてはならない。エンディングは、セグメントが終わる前の endLength の小節で演奏を開始する。エンディングが endLength の小節の長さより短い場合、音楽は基本グルーブ レベルに戻る。

参照

DirectMusicComposer8.ComposeSegmentFromShape、DirectMusicComposer8.ComposeSegmentFromTemplate


DirectMusicComposer8.ComposeTransition

あるセクション セグメントから別のセクション セグメントへのトランジションをアレンジする。

object.ComposeTransition(fromSeg As DirectMusicSegment8, _
    toSeg As DirectMusicSegment8, _
    mtTime As Long, _
    lCommand As Long, _
    lFlags As Long, _
    chordmap As DirectMusicChordMap8 _
) As DirectMusicSegment8

指定項目

object
DirectMusicComposer8 オブジェクトを指定する。
fromSeg
トランジションのアレンジ元として使用するセクション セグメントを表す DirectMusicSegment8 オブジェクト。
toSeg
移行先セクション。トランジションはこのセクションへ円滑に移行する。lFlags が DMUS_COMPOSEF_MODULATE を含んでいない場合、NULL でもよい。
mtTime
fromSeg のセクション内でトランジションのアレンジを開始するタイム。
lCommand
トランジションを作成するときに使われる装飾。「CONST_DMUS_COMMANDT_TYPES」を参照すること。この値が DMUS_COMMANDT_ENDANDINTRO の場合、メソッドは、fromSeg のエンディングと toSeg のイントロを含むセグメントをアレンジする。
lFlags
コンポーザ オプション。このパラメータは、CONST_DMUS_COMPOSEF_FLAGS 列挙型の 1 つまたは複数の値を保持していてもよい。
chordmap
トランジションのアレンジに使用するコード マップを表す DirectMusicChordMap8 オブジェクト。「注意」を参照すること。

戻り値

DirectMusicSegment8 オブジェクトを返す。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

DMUS_E_INVALIDARG
DMUS_E_OUTOFMEMORY

注意

chordmap の値は NULL でもよい。値が NULL の場合、コード マップ トラックからコード マップを取得する試みが行われる。最初に toSeg、次に fromSeg が試される。どのセグメントにもコード マップ トラックが含まれない場合は、mtTime に fromSeg 内で発生するコードがトランジションのコードとして使用される。

コンポーザは、最初に fromSeg 内、次に toSeg 内でテンポを探す。どのセグメントにもテンポ トラックがない場合、トランジション セグメントのテンポはスタイルから取得される。

参照

DirectMusicComposer8.AutoTransition


DirectMusicLoader8

ミュージック データと音色データを表すオブジェクトの検索とロードに使われる。

このオブジェクトは、DirectX8.DirectMusicLoaderCreate メソッドを使って取得する。

ほかのオブジェクトによって参照されるオブジェクトは、自動的にロードされる。たとえば、スタイルには、その他のファイル内のバンドとコレクションへの参照が含まれる場合があり、これらの参照がロードされるのは、DirectMusicLoader8.LoadStyle メソッドを呼び出したときである。

DirectMusicLoader8 のメソッドは、以下のグループにまとめることができる。

ロード | LoadBand
 | LoadBandFromResource
 | LoadChordMap
 | LoadChordMapFromResource
 | LoadCollection
 | LoadCollectionFromResource
 | LoadSegment
 | LoadSegmentFromResource
 | LoadStyle
 | LoadStyleFromResource
検索 | SetSearchDirectory


DirectMusicLoader8.LoadBand

ファイルからバンドをロードする。

object.LoadBand(filename As String) As DirectMusicBand8

指定項目

object
DirectMusicLoader8 オブジェクトを指定する。
filename
バンドを含むファイルの名前。カレント ディレクトリ内または DirectMusicLoader8.SetSearchDirectory によって設定されるディレクトリ内にファイルがない場合は、フルパスを指定しなければならない。

戻り値

DirectMusicBand8 オブジェクトを返す。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

DMUS_E_FAIL
DMUS_E_INVALIDARG
DMUS_E_OUTOFMEMORY
DMUS_E_INVALID_BAND
DMUS_E_LOADER_FAILEDOPEN
DMUS_E_LOADER_FAILEDCREATE
DMUS_E_LOADER_FORMATNOTSUPPORTED

参照

DirectMusicLoader8.LoadBandFromResource


DirectMusicLoader8.LoadBandFromResource

リソースからバンドをロードする。

object.LoadBandFromResource( _
    moduleName As String, _
    resourceName As String _
) As DirectMusicBand8

指定項目

object
DirectMusicLoader8 オブジェクトを指定する。
moduleName
リソースを含むモジュールの名前。
resourceName
バンドを含むリソースの識別子。リソースのタイプは "DMBAND" でなければならない。

戻り値

DirectMusicBand8 オブジェクトを返す。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

DMUS_E_FAIL
DMUS_E_INVALIDARG
DMUS_E_OUTOFMEMORY
DMUS_E_INVALID_BAND
DMUS_E_LOADER_FAILEDCREATE
DMUS_E_LOADER_FORMATNOTSUPPORTED

参照

DirectMusicLoader8.LoadBand


DirectMusicLoader8.LoadChordMap

ファイルからコード マップをロードする。

object.LoadChordMap(filename As String _
) As DirectMusicChordMap8

指定項目

object
DirectMusicLoader8 オブジェクトを指定する。
filename
コード マップを含むファイルの名前。カレント ディレクトリ内または DirectMusicLoader8.SetSearchDirectory によって設定されるディレクトリ内にファイルがない場合は、フルパスを指定しなければならない。

戻り値

DirectMusicChordMap8 オブジェクトを返す。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

DMUS_E_CHUNKNOTFOUND
DMUS_E_FAIL
DMUS_E_INVALIDARG
DMUS_E_OUTOFMEMORY
DMUS_E_LOADER_FAILEDOPEN
DMUS_E_LOADER_FAILEDCREATE
DMUS_E_LOADER_FORMATNOTSUPPORTED

参照

DirectMusicLoader8.LoadChordMapFromResource


DirectMusicLoader8.LoadChordMapFromResource

リソースからコード マップをロードする。

object.LoadChordMapFromResource( _
    moduleName As String, _
    resourceName As String _
) As DirectMusicChordMap8

指定項目

object
DirectMusicLoader8 オブジェクトを指定する。
moduleName
リソースを含むモジュールの名前。
resourceName
コード マップを含むリソースの識別子。リソースのタイプは "DMCHORD" でなければならない。

戻り値

DirectMusicChordMap8 オブジェクトを返す。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

DMUS_E_CHUNKNOTFOUND
DMUS_E_FAIL
DMUS_E_INVALIDARG
DMUS_E_OUTOFMEMORY
DMUS_E_LOADER_FAILEDOPEN
DMUS_E_LOADER_FAILEDCREATE
DMUS_E_LOADER_FORMATNOTSUPPORTED

参照

DirectMusicLoader8.LoadChordMap


DirectMusicLoader8.LoadCollection

ファイルから DLS コレクションをロードする。

object.LoadCollection(filename As String _
) As DirectMusicCollection8

指定項目

object
DirectMusicLoader8 オブジェクトを指定する。
filename
DLS コレクションを含むファイルの名前。カレント ディレクトリ内または DirectMusicLoader8.SetSearchDirectory によって設定されるディレクトリ内にファイルがない場合は、フルパスを指定しなければならない。

戻り値

DirectMusicCollection8 オブジェクトを返す。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

DMUS_E_CHUNKNOTFOUND
DMUS_E_FAIL
DMUS_E_INVALIDARG
DMUS_E_OUTOFMEMORY
DMUS_E_LOADER_FAILEDOPEN
DMUS_E_LOADER_FAILEDCREATE
DMUS_E_LOADER_FORMATNOTSUPPORTED
DMUS_E_NOTADLSCOL

参照

DirectMusicLoader8.LoadCollectionFromResource


DirectMusicLoader8.LoadCollectionFromResource

リソースから DLS コレクションをロードする。

object.LoadCollectionFromResource( _
  moduleName As String, _
  resourceName As String _
) As DirectMusicCollection8

指定項目

object
DirectMusicLoader8 オブジェクトを指定する。
moduleName
リソースを含むモジュールの名前。
resourceName
コレクションを含むリソースの識別子。リソースのタイプは "DMCOLL" でなければならない。

戻り値

DirectMusicCollection8 オブジェクトを返す。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

DMUS_E_CHUNKNOTFOUND
DMUS_E_FAIL
DMUS_E_INVALIDARG
DMUS_E_OUTOFMEMORY
DMUS_E_LOADER_FAILEDOPEN
DMUS_E_LOADER_FAILEDCREATE
DMUS_E_LOADER_FORMATNOTSUPPORTED
DMUS_E_NOTADLSCOL

参照

DirectMusicLoader8.LoadCollection


DirectMusicLoader8.LoadSegment

MIDI ファイル、ウェーブ ファイル、または DirectMusic Producer でオーサリングされたセグメント ファイルからセグメントをロードする。

object.LoadSegment(filename As String _
) As DirectMusicSegment8

指定項目

object
DirectMusicLoader8 オブジェクトを指定する。
filename
セグメントを含むファイルの名前。カレント ディレクトリ内または DirectMusicLoader8.SetSearchDirectory によって設定されるディレクトリ内にファイルがない場合は、フルパスを指定しなければならない。

戻り値

DirectMusicSegment8 オブジェクトを返す。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

DMUS_E_CHUNKNOTFOUND
DMUS_E_FAIL
DMUS_E_INVALIDARG
DMUS_E_OUTOFMEMORY
DMUS_E_LOADER_FAILEDOPEN
DMUS_E_LOADER_FAILEDCREATE
DMUS_E_LOADER_FORMATNOTSUPPORTED

参照

DirectMusicLoader8.LoadSegmentFromResource


DirectMusicLoader8.LoadSegmentFromResource

リソースからセグメントをロードする。ロードされるセグメントの形式は、MIDI ファイル、ウェーブ ファイル、または DirectMusic Producer でオーサリングされたセグメントである。

object.LoadSegmentFromResource( _
    moduleName As String, _
    resourceName As String _
) As DirectMusicSegment8

指定項目

object
DirectMusicLoader8 オブジェクトを指定する。
moduleName
リソースを含むモジュールの名前。リソースのタイプは "DMSEG" でなければならない。
resourceName
セグメントを含むリソースの識別子。

戻り値

DirectMusicSegment8 オブジェクトを返す。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

DMUS_E_CHUNKNOTFOUND
DMUS_E_FAIL
DMUS_E_INVALIDARG
DMUS_E_OUTOFMEMORY
DMUS_E_LOADER_FAILEDOPEN
DMUS_E_LOADER_FAILEDCREATE
DMUS_E_LOADER_FORMATNOTSUPPORTED
DMUS_E_UNSUPPORTED_STREAM

参照

DirectMusicLoader8.LoadSegment


DirectMusicLoader8.LoadStyle

ファイルからスタイル オブジェクトをロードする。

object.LoadStyle(filename As String) As DirectMusicStyle8

指定項目

object
DirectMusicLoader8 オブジェクトを指定する。
filename
スタイル オブジェクトを含むファイルの名前。カレント ディレクトリ内または DirectMusicLoader8.SetSearchDirectory によって設定されるディレクトリ内にファイルがない場合は、フルパスを指定しなければならない。

戻り値

DirectMusicStyle8 オブジェクトを返す。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

DMUS_E_CHUNKNOTFOUND
DMUS_E_FAIL
DMUS_E_INVALIDARG
DMUS_E_OUTOFMEMORY
DMUS_E_LOADER_FAILEDOPEN
DMUS_E_LOADER_FAILEDCREATE
DMUS_E_LOADER_FORMATNOTSUPPORTED

参照

DirectMusicLoader8.LoadStyleFromResource


DirectMusicLoader8.LoadStyleFromResource

リソースからスタイル オブジェクトをロードする。

object.LoadStyleFromResource( _
    moduleName As String, _
    resourceName As String _
) As DirectMusicStyle8

指定項目

object
DirectMusicLoader8 オブジェクトを指定する。
moduleName
リソースを含むモジュールの名前。
resourceName
スタイル オブジェクトを含むリソースの識別子。リソースのタイプは "DMSTYLE" でなければならない。

戻り値

DirectMusicStyle8 オブジェクトを返す。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

DMUS_E_CHUNKNOTFOUND
DMUS_E_FAIL
DMUS_E_INVALIDARG
DMUS_E_OUTOFMEMORY
DMUS_E_LOADER_FAILEDOPEN
DMUS_E_LOADER_FAILEDCREATE
DMUS_E_LOADER_FORMATNOTSUPPORTED

参照

DirectMusicLoader8.LoadStyle


DirectMusicLoader8.SetSearchDirectory

フル パスが指定されなかった場合に DirectMusicLoader8.LoadBand、DirectMusicLoader8.LoadChordmap、DirectMusicLoader8.LoadCollection、DirectMusicLoader8.LoadSegment、および DirectMusicLoader8.LoadStyle の各メソッドによって検索されるディレクトリを設定する。

object.SetSearchDirectory(dir As String)

指定項目

object
DirectMusicLoader8 オブジェクトを指定する。
dir
検索されるディレクトリ。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

DMUS_E_OUTOFMEMORY
DMUS_E_LOADER_BADPATH

注意

検索パスを設定した後、ローダーはファイル名を使ってオブジェクトをロードするときに、フル パス名を必要としない。この結果、ほかのオブジェクトを参照するオブジェクトは、フル パスを把握していなくてもファイル名だけでそれらを検索できる。


DirectMusicPerformance8

音楽再生の総合的なマネージャである。このオブジェクトは、パフォーマンス チャンネルのオーディオパスへのマッピング、セグメントの演奏、メッセージの送信、イベント通知の送受信、およびミュージック パラメータの設定と取得を行う。また、タイミングに関する情報の取得、およびシステム間でタイムとミュージック値を変換するためのメソッドも備えている。

アプリケーションが 2 つ以上の完全な音楽セットを同時に演奏したい場合、複数のパフォーマンス オブジェクトを作成することにより、そのような演奏が行える。個別のパフォーマンスは独立したテンポ マップに従うため、完全に非同期に演奏されるが、一方で 1 つのパフォーマンス内のすべてのセグメントは固定的なステップで演奏される。

DirectMusicPerformance8 オブジェクトは、DirectX8.DirectMusicPerformanceCreate メソッドを使って取得する。

DirectMusicPerformance8 クラスのメソッドは、以下のグループにまとめることができる。

オーディオパス | CreateAudioPath
 | CreateStandardAudioPath
 | GetDefaultAudioPath
 | SetDefaultAudioPath
初期化とクリーンアップ | InitAudio
 | CloseDown
メッセージ | SendCurvePMSG
 | SendMIDIPMSG
 | SendNotePMSG
 | SendPatchPMSG
 | SendTempoPMSG
 | SendTimeSigPMSG
 | SendTransposePMSG
通知 | AddNotificationType
 | GetNotificationPMSG
 | RemoveNotificationType
 | SetNotificationHandle
パラメータ | GetChordmap
 | GetCommand
 | GetGrooveLevel
 | GetMasterAutoDownload
 | GetMasterGrooveLevel
 | GetMasterTempo
 | GetMasterVolume
 | GetStyle
 | GetTempo
 | GetTimeSig
 | Reset
 | SetMasterAutoDownload
 | SetMasterGrooveLevel
 | SetMasterTempo
 | SetMasterVolume
セグメント | GetSegmentState
 | IsPlaying
 | PlaySegmentEx
 | StopEx
タイミング | AdjustTime
 | ClockToMusicTime
 | GetBumperLength
 | GetClockTime
 | GetLatencyTime
 | GetMusicTime
 | GetPrepareTime
 | GetQueueTime
 | GetResolvedTime
 | MusicToClockTime
 | SetBumperLength
 | SetPrepareTime
その他 | Invalidate


DirectMusicPerformance8.AddNotificationType

要求されたタイプのイベントが発生するたびに、パフォーマンスが通知メッセージを生成するよう設定する。

object.AddNotificationType( _
    type As CONST_DMUS_NOTIFICATION_TYPE)

指定項目

object
DirectMusicPerformance8 オブジェクトを指定する。
type
通知メッセージが送信されるイベントのタイプ。指定可能な値については、「CONST_DMUS_NOTIFICATION_TYPE」を参照すること。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

DMUS_E_INVALIDARG
DMUS_E_OUTOFMEMORY

参照

DirectMusicPerformance8.RemoveNotificationType


DirectMusicPerformance8.AdjustTime

パフォーマンスの内部時間を前方または後方に調整する。このメソッドはほとんどの場合、ほかのソースとの同期させる際にずれを補正するために使用される。

object.AdjustTime(tAmount As Long)

指定項目

object
DirectMusicPerformance8 オブジェクトを指定する。
tAmount
加算または減算される時間。クロック タイム単位で表す。－ 1,000 ～から 1,000 (－ 1 秒～ ＋ 1 秒) の数値を指定する。

エラー コード

失敗した場合はエラーが発生し、Err.Number に DMUS_E_INVALIDARG が設定される。

注意

調整された時間は、DirectMusic によって内部的に使用される。DirectMusicPerformance8.GetClockTime メソッドが取得するタイムには反映されない。


DirectMusicPerformance8.ClockToMusicTime

クロック タイムをミュージック タイムに変換する。

object.ClockToMusicTime(ctTime As Long) As Long

指定項目

object
DirectMusicPerformance8 オブジェクトを指定する。
ctTime
変換されるタイム。クロック タイム単位で表す。

戻り値

等価のミュージック タイムを返す。

エラー コード

失敗した場合はエラーが発生し、Err.Number に DMUS_E_NO_MASTER_CLOCK が設定される。

注意

このメソッドは、パフォーマンスの時間ではなく、パフォーマンスの開始からのタイムのオフセットを変換する。ミュージック タイムとクロック タイムの単位の比率はテンポに依存するため、変換時には、パフォーマンスが開始されてからのテンポの変更がすべて考慮される。パフォーマンスについてマスタ テンポが設定されている場合は、同様に考慮される。

ミュージック タイムはクロック タイムほど正確ではないため、切り捨てが行われる。

参照

DirectMusicPerformance8.MusicToClockTime、クロック タイムとミュージック タイム


DirectMusicPerformance8.CloseDown

パフォーマンスを終了する。パフォーマンス オブジェクトを作成し、それに対して DirectMusicPerformance8.InitAudio を呼び出したアプリケーションは、パフォーマンス オブジェクトを解放する前に、CloseDown を呼び出さなければならない。

object.CloseDown()

指定項目

object
DirectMusicPerformance8 オブジェクトを指定する。

エラー コード

失敗した場合はエラーが発生し、Err.Number が設定される。

注意

CloseDown の呼び出しを忘れると、メモリ リークやアプリケーション障害が発生することがある。

DirectMusicPerformance8.InitAudio の呼び出しで DirectSound8 オブジェクトを作成したが、アプリケーションにいずれのオブジェクトも返されなかった場合は、CloseDown も DirectSound およびすべての DirectSound バッファを解放する。アプリケーションで DirectSound バッファ オブジェクトに変数を設定していた場合は、Closedown を呼び出す前に、必ずそれらの変数をスコープ外に出すか、Nothing に設定する。

アプリケーションで明示的に DirectSound8 オブジェクトを作成した場合、または InitAudio から DirectSound8 オブジェクトを取得した場合は、アプリケーションで DirectSound を解放する必要がある。

CloseDown は、まだアンロードされていない任意のダウンロード済みの音色も解放する。


DirectMusicPerformance8.CreateAudioPath

パフォーマンスから DirectSound バッファへのデータ フロー内の各ステージを表す、オーディオパス オブジェクトを作成する。

object.CreateAudioPath( _
  SourceConfig As Unknown _
) As DirectMusicAudioPath8

指定項目

object
DirectMusicPerformance8 オブジェクトを指定する。
SourceConfig
オーディオパス構成を表すオブジェクト。このオブジェクトは、通常、DirectMusicSegment8.GetAudioPathConfig メソッドを使用して、セグメントから取得する。

戻り値

DirectMusicAudioPath8 オブジェクトを返す。

エラー コード

失敗した場合は、エラーが発生する。Err.Number に次のいずれかの値が設定される。

DMUS_E_NOT_INIT
DMUS_E_AUDIOPATHS_NOT_VALID
DMUS_E_OUTOFMEMORY


DirectMusicPerformance8.CreateStandardAudioPath

パフォーマンスから DirectSound バッファへのデータ フロー内の各ステージを表す、オブジェクトを作成する。このメソッドを使用すると、DirectMusicPerformance8.CreateAudioPath でソース ファイルに定義されたオーディオパスを作成する代わりに、基本的な事前定義オーディオパスを作成することができる。

object.CreateStandardAudioPath( _
  lType As CONST_DMUSIC_STANDARD_AUDIO_PATH, _
  lPChannelCount As Long, _
  fActive As Boolean _
) As DirectMusicAudioPath8

指定項目

object
DirectMusicPerformance8 オブジェクトを指定する。
lType
CONST_DMUSIC_STANDARD_AUDIO_PATH 列挙型の定数のいずれかで指定される、パスのタイプ。これらのオーディオパス タイプの詳細については、「標準オーディオパス」を参照すること。
lPChannelCount
パス内のパフォーマンス チャンネルの数を指定する値。
fActive
作成時にパスをアクティブにするかどうかを指定するブール型の値。

戻り値

DirectMusicAudioPath8 オブジェクトを返す。

エラー コード

成功した場合は S_OK を返す。

失敗した場合は次のエラー値のいずれかを返す。

DMUS_E_NOT_INIT
DMUS_E_AUDIOPATHS_NOT_VALID
DMUS_E_INVALIDARG
DMUS_E_OUTOFMEMORY


DirectMusicPerformance8.GetBumperLength

メッセージがポート バッファに置かれてから、ポートによる処理が開始されるまでの時間を取得する。

object.GetBumperLength() As Long

指定項目

object
DirectMusicPerformance8 オブジェクトを指定する。

戻り値

バンパー時間の長さをミリ秒単位で返す。

エラー コード

失敗した場合はエラーが発生し、Err.Number が設定される。

注意

デフォルトの値は 50 ミリ秒 (ms) である。

参照

DirectMusicPerformance8.SetBumperLength


DirectMusicPerformance8.GetChordmap

パフォーマンスの制御セグメントからコード マップを取得する。

object.GetChordMap( _
  mtTime As Long, _
  mtUntil As Long _
) As DirectMusicChordMap8

指定項目

object
DirectMusicPerformance8 オブジェクトを指定する。
mtTime
コード マップが取得されるタイム。ミュージック タイムで指定する。
mtUntil
そのコード マップが無効になるミュージック タイム (mtTime からの相対タイム) を受け取る、長整数型 (Long) の変数。この変数が値 0 を返した場合、コード マップが常に有効になっているか、コード マップが無効になるタイムが不明であることを意味する。「注意」を参照すること。

戻り値

DirectMusicChordMap8 オブジェクトを返す。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

DMUS_E_NO_MASTER_CLOCK
DMUS_E_GET_UNSUPPORTED
DMUS_E_NOT_FOUND
DMUS_E_TRACK_NOT_FOUND

注意

通常、プライマリ セグメントは制御セグメントである。ただし、セカンダリ セグメントを演奏するときは、これを制御セグメントとして指定できる。別の制御セグメントが挿入される場合、このメソッドによって返されるタイムは、mtUntil に返されるタイムの前に無効になることがある。

参照

CONST_DMUS_SEGF_FLAGS


DirectMusicPerformance8.GetClockTime

現在のタイムを取得する。

object.GetClockTime() As Long

指定項目

object
DirectMusicPerformance8 オブジェクトを指定する。

戻り値

任意の開始タイムからの相対タイムを返す。約 1 ミリ秒の単位で表される。

エラー コード

失敗した場合はエラーが発生し、Err.Number に DMUS_E_NO_MASTER_CLOCK が設定される。

参照

DirectMusicPerformance8.GetMusicTime、クロック タイムとミュージック タイム


DirectMusicPerformance8.GetCommand

パフォーマンスの制御セグメントからコマンドを取得する。コマンドは、指定のタイムに演奏されているパターンのタイプを示す。

object.GetCommand( _
  mtTime As Long, _
  mtUntil As Long _
) As Byte

指定項目

object
DirectMusicPerformance8 オブジェクトを指定する。
mtTime
コマンドが取得されるタイム。ミュージック タイムで指定する。
mtUntil
コード マップが無効になるミュージック タイム (mtTime からの相対タイム) を受け取る変数。この変数が値 0 を返した場合、コマンドが常に有効になっているか、コマンドが無効になるタイムが不明であることを意味する。「注意」を参照すること。

戻り値

コマンド タイプを返す。「CONST_DMUS_COMMANDT_TYPES」を参照すること。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

DMUS_E_NO_MASTER_CLOCK
DMUS_E_GET_UNSUPPORTED
DMUS_E_NOT_FOUND
DMUS_E_TRACK_NOT_FOUND

注意

通常、プライマリ セグメントは制御セグメントである。ただし、セカンダリ セグメントを演奏するときは、これを制御セグメントとして指定できる。別の制御セグメントが挿入される場合、このメソッドによって返されるタイムは、mtUntil に返されるタイムの前に無効になることがある。

参照

CONST_DMUS_SEGF_FLAGS


DirectMusicPerformance8.GetDefaultAudioPath

DirectMusicPerformance8.InitAudio または DirectMusicPerformance8.SetDefaultAudioPath で設定されたデフォルトのオーディオパスを取得する。

object.GetDefaultAudioPath() As DirectMusicAudioPath8

指定項目

object
DirectMusicPerformance8 オブジェクトを指定する。

戻り値

DirectMusicAudioPath8 オブジェクトを返す。

エラー コード

失敗した場合は、エラーが発生する。Err.Number に次のいずれかの値が設定される。

DMUS_E_AUDIOPATHS_NOT_VALID
DMUS_E_NOT_INIT


DirectMusicPerformance8.GetGrooveLevel

パフォーマンスの制御セグメントからグルーブ レベルを取得する。グルーブ レベルによって、指定のタイムに演奏できるパターンが決まる。

object.GetGrooveLevel( _
  mtTime As Long, _
  mtUntil As Long _
) As Byte

指定項目

object
DirectMusicPerformance8 オブジェクトを指定する。
mtTime
グルーブ レベルが取得されるタイム。ミュージック タイムで指定する。
mtUntil
そのグルーブ レベルが無効になるミュージック タイム (mtTime からの相対タイム) を受け取る、長整数型 (Long) の変数。この変数が値 0 を返した場合、グルーブ レベルが常に有効になっているか、グルーブ レベルが無効になるタイムが不明であることを意味する。「注意」を参照すること。

戻り値

1 から 100 までの範囲の値を返す。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

DMUS_E_NO_MASTER_CLOCK
DMUS_E_GET_UNSUPPORTED
DMUS_E_NOT_FOUND
DMUS_E_TRACK_NOT_FOUND

注意

通常、プライマリ セグメントは制御セグメントである。ただし、セカンダリ セグメントを演奏するときは、これを制御セグメントとして指定できる。別の制御セグメントが挿入される場合、このメソッドによって返されるタイムは、mtUntil に返されるタイムの前に無効になることがある。

参照

DirectMusicPerformance8.GetMasterGrooveLevel、CONST_DMUS_SEGF_FLAGS


DirectMusicPerformance8.GetLatencyTime

現在の遅延時間を取得する。遅延時間とは、メッセージがレンダリングのためにポートに送信されるタイムである。

object.GetLatencyTime() As Long

指定項目

object
DirectMusicPerformance8 オブジェクトを指定する。

戻り値

遅延時間をクロック タイム単位で返す。

エラー コード

失敗した場合はエラーが発生し、Err.Number に DMUS_E_NO_MASTER_CLOCK が設定される。


DirectMusicPerformance8.GetMasterAutoDownload

音色の自動ダウンロードを行うための現在の設定を取得する。

object.GetMasterAutoDownload() As Boolean

指定項目

object
DirectMusicPerformance8 オブジェクトを指定する。

戻り値

自動ダウンロードが有効な場合は TRUE、無効な場合は FALSE を返す。デフォルト値は FALSE である。

エラー コード

失敗した場合はエラーが発生し、Err.Number が設定される。

参照

DirectMusicPerformance8.SetMasterAutoDownload、DirectMusicSegment8.SetAutoDownloadEnable


DirectMusicPerformance8.GetMasterGrooveLevel

現在のマスタ グルーブ レベルを取得する。マスタ グルーブ レベルとは、パフォーマンス内のすべてのグルーブ レベルに追加される値である。返される値は 1 ～ 100 の範囲に収まるように必要に応じて調整される。

object.GetMasterGrooveLevel() As Integer

指定項目

object
DirectMusicPerformance8 オブジェクトを指定する。

戻り値

マスタ グルーブ レベルを返す。

エラー コード

失敗した場合はエラーが発生し、Err.Number が設定される。

参照

DirectMusicPerformance8.GetGrooveLevel、DirectMusicPerformance8.SetMasterGrooveLevel


DirectMusicPerformance8.GetMasterTempo

現在のマスタ テンポを取得する。

object.GetMasterTempo() As Single

指定項目

object
DirectMusicPerformance8 オブジェクトを指定する。

戻り値

0.01 から 100.0 までの範囲の値を返す。

エラー コード

失敗した場合はエラーが発生し、Err.Number が設定される。

注意

マスタ テンポは、最終的な出力ツールによってテンポに適用されるスケーリング係数である。デフォルトでは 1 が設定される。値が 0.5 の場合、テンポは半分になり、2.0 の場合は 2 倍になる。

参照

DirectMusicPerformance8.SetMasterTempo


DirectMusicPerformance8.GetMasterVolume

現在のマスタ ボリュームを取得する。

object.GetMasterVolume() As Long

指定項目

object
DirectMusicPerformance8 オブジェクトを指定する。

戻り値

現在のマスタ ボリュームを 1/100 デシベル単位で返す。

エラー コード

失敗した場合はエラーが発生し、Err.Number が設定される。

注意

マスタ ボリュームは、パフォーマンス全体のデフォルト ボリュームに適用される増幅係数または減衰係数である。設定できる値の範囲はポートによって決まる。

参照

DirectMusicPerformance8.SetMasterVolume


DirectMusicPerformance8.GetMusicTime

パフォーマンスの現在タイムをミュージック タイム単位で取得する。

object.GetMusicTime() As Long

指定項目

object
DirectMusicPerformance8 オブジェクトを指定する。

戻り値

現在のタイムをミュージック タイム単位で返す。

エラー コード

失敗した場合はエラーが発生し、Err.Number に DMUS_E_NO_MASTER_CLOCK が設定される。

参照

DirectMusicPerformance8.GetClockTime、クロック タイムとミュージック タイム


DirectMusicPerformance8.GetNotificationPMsg

保留中の通知メッセージを取得する。

object.GetNotificationPMSG( _
  message As DMUS_NOTIFICATION_PMSG _
) As Boolean

指定項目

object
DirectMusicPerformance8 オブジェクトを指定する。
message
メッセージを受け取る DMUS_NOTIFICATION_PMSG 型。

戻り値

メッセージが受け取られた場合は TRUE を返す。保留にされているメッセージがなかった場合は FALSE を返す。

エラー コード

失敗した場合はエラーが発生し、Err.Number が設定される。


DirectMusicPerformance8.GetPrepareTime

メッセージが準備されてから、処理され、スピーカから聞こえるまでのだいたいの時間を取得する。

object.GetPrepareTime() As Long

指定項目

object
DirectMusicPerformance8 オブジェクトを指定する。

戻り値

準備時間をミリ秒単位で返す。

エラー コード

失敗した場合はエラーが発生し、Err.Number が設定される。

注意

デフォルトの値は 1,000 ミリ秒 (ms) である。

参照

DirectMusicPerformance8.SetPrepareTime、準備時間


DirectMusicPerformance8.GetQueueTime

現在のキュー (またはフラッシュ) 時間を取得する。このタイムより早いタイムのタイム スタンプを持つメッセージは、既にポートのキューに入れられており、無効にすることができない。

object.GetQueueTime() As Long

指定項目

object
DirectMusicPerformance8 オブジェクトを指定する。

戻り値

キュー時間をクロック タイム単位で返す。

エラー コード

失敗した場合はエラーが発生し、Err.Number に DMUS_E_NO_MASTER_CLOCK が設定される。

注意

キュー時間は、DirectMusicPerformance8.GetLatencyTime と DirectMusicPerformance8.GetBumperLength の各メソッドが返す値を加算した値に等しい。

セグメントを即座に停止すると、既に送信されたものの、ポート バッファのキューに入れられていないメッセージはすべてフラッシュ (解放) される。セグメントの演奏を最後に停止した時点から再開したい場合は、新しい開始ポイントを、セグメントを停止したときのセグメント内におけるキュー タイムのオフセットに設定する。

参照

DirectMusicPerformance8.Invalidate


DirectMusicPerformance8.GetResolvedTime

指定されたタイムを、指定された境界に調整する。

object.GetResolvedTime( _
  ctTime As Long, _
  flags As Long _
) As Long

指定項目

object
DirectMusicPerformance8 オブジェクトを指定する。
ctTime
調整されるべきタイム。クロック タイム単位で指定する。このタイムが現在のタイムより早い場合は、現在のタイムが使用される。
flags
目的の分解能を記述する、以下の 1 つ以上の CONST_DMUS_SEGF_FLAGS。
DMUS_SEGF_AFTERLATENCYTIME
遅延時間の後のタイムに解決する。
DMUS_SEGF_AFTERPREPARETIME
準備時間の後のタイムに解決する。
DMUS_SEGF_AFTERQUEUETIME
キュー時間の後のタイムに解決する。
DMUS_SEGF_BEAT
拍境界上のタイムに解決する。
DMUS_SEGF_GRID
グリッド境界上のタイムに解決する。
DMUS_SEGF_MARKER
マーカーに解決する。
DMUS_SEGF_MEASURE
小節境界上のタイムに解決する。
DMUS_SEGF_SEGMENTEND
セグメントの終端に解決する。

戻り値

調整されたタイムを返す。

エラー コード

失敗した場合はエラーが発生し、Err.Number が設定される。

注意

返されるタイムは、指定されたタイムの後の、指定の境界に属する可能な限り早いタイムである。


DirectMusicPerformance8.GetSegmentState

プライマリ セグメントの演奏状態を表すオブジェクトを取得する。

object.GetSegmentState( _
  mtTime As Long _
) As DirectMusicSegmentState8

指定項目

object
DirectMusicPerformance8 オブジェクトを指定する。
mtTime
セグメント状態が取得されるタイム。ミュージック タイムで指定する。

戻り値

DirectMusicSegmentState8 オブジェクトを返す。

エラー コード

失敗した場合はエラーが発生し、Err.Number に DMUS_E_NOT_FOUND が設定される。

注意

現在演奏中のセグメント状態を取得するには、DirectMusicPerformance8.GetMusicTime メソッドが返すタイムを渡す。ここで言う "現在演奏中" とは、メッセージを演奏するために現在呼び出されていることを意味する。遅延時間が存在するため、必ずしも現在演奏されているセグメント状態が現在スピーカから聞こえているとは限らない。

また、DirectMusicPerformance8.PlaySegmentEx を呼び出した直後にセグメント状態を取り出す場合は、遅延時間を考慮して mtTime の値に 150 を加算するとよい。


DirectMusicPerformance8.GetStyle

指定のタイムにおける、制御セグメントの基調となるスタイルを取得する。

object.GetStyle( _
  mtTime As Long, _
  mtUntil As Long _
) As DirectMusicStyle8

指定項目

object
DirectMusicPerformance8 オブジェクトを指定する。
mtTime
スタイルが取得されるタイム。ミュージック タイムで指定する。
mtUntil
そのスタイルが無効になるミュージック タイム (mtTime からの相対タイム) を受け取る、長整数型 (Long) の変数。この変数が値 0 を返した場合、スタイルが常に有効になっているか、スタイルが無効になるタイムが不明であることを意味する。「注意」を参照すること。

戻り値

DirectMusicStyle8 オブジェクトを返す。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

DMUS_E_NO_MASTER_CLOCK
DMUS_E_GET_UNSUPPORTED
DMUS_E_NOT_FOUND
DMUS_E_TRACK_NOT_FOUND

注意

通常、プライマリ セグメントは制御セグメントである。ただし、セカンダリ セグメントを演奏するときは、これを制御セグメントとして指定できる。別の制御セグメントが挿入される場合、このメソッドによって返されるタイムは、mtUntil に返されるタイムの前に無効になることがある。


DirectMusicPerformance8.GetTempo

指定のタイムのテンポを取得する。

object.GetTempo( _
  mtTime As Long, _
  mtUntil As Long _
) As Double

指定項目

object
DirectMusicPerformance8 オブジェクトを指定する。
mtTime
テンポが取得されるタイム。ミュージック タイムで指定する。このタイムまたはこれより前に行われたテンポの最後の変更を使って、テンポが決まる。
mtUntil
そのテンポが無効になるミュージック タイム (mtTime からの相対タイム) を受け取る、長整数型 (Long) の変数。この変数が値 0 を返した場合、テンポが常に有効になっているか、テンポが無効になるタイムが不明であることを意味する。

戻り値

1 分あたりの拍数で表されたテンポを返す。この値は DMUS_TEMPO_MIN ～ DMUS_TEMPO_MAX の範囲にある (「CONST_DMUS」を参照)。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

DMUS_E_NO_MASTER_CLOCK
DMUS_E_GET_UNSUPPORTED
DMUS_E_NOT_FOUND
DMUS_E_TRACK_NOT_FOUND


DirectMusicPerformance8.GetTimeSig

指定のタイムでの拍子記号を取得する。

object.GetTimeSig( _
  mtTime As Long, _
  mtUntil As Long, _
  timeSig As DMUS_TIMESIGNATURE)

指定項目

object
DirectMusicPerformance8 オブジェクトを指定する。
mtTime
拍子記号を取得するタイムを指定する値。ミュージック タイムで指定する。このタイムまたはこれより前に行われた拍子記号の最後の変更を使って、拍子記号が決まる。
mtUntil
その拍子記号が無効になるミュージック タイム (mtTime からの相対タイム) を受け取る、長整数型 (Long) の変数。この変数が値 0 を返した場合、拍子記号が常に有効になっているか、拍子記号が無効になるタイムが不明であることを意味する。「注意」を参照すること。
timeSig
拍子記号に関する情報を受け取る DMUS_TIMESIGNATURE 型。mtTime メンバは、要求されたタイムから、拍子記号の最後の変更が行われた時点までのオフセットを受け取る。常に 0 未満の値になる。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

DMUS_E_NO_MASTER_CLOCK
DMUS_E_GET_UNSUPPORTED
DMUS_E_NOT_FOUND
DMUS_E_TRACK_NOT_FOUND


DirectMusicPerformance8.InitAudio

パフォーマンスを初期化し、オプションでデフォルトのオーディオパスをセットアップする。このメソッドは、オーディオパスを使ってパフォーマンスを演奏する前に、呼び出す必要がある。

object.InitAudio( _
  hwnd As Long, _
  lFlags As CONST_DMUS_AUDIO, _
  AudioParams As DMUS_AUDIOPARAMS, _
  [DirectSound As DirectSound8], _
  [lDefaultPathType As CONST_DMUSIC_STANDARD_AUDIO_PATH], _
  [lPChannelCount As Long] )

指定項目

object
DirectMusicPerformance8 オブジェクトを指定する。
hwnd
DirectSound の作成に使用するウィンドウ ハンドル。0 を指定すると、前面ウィンドウが使用される。「注意」を参照すること。

DirectSound8 オブジェクトを DirectSound のメソッドに渡す場合、このパラメータは無視される。その場合、アプリケーションは、DirectSound8.SetCooperativeLevel を使ってウィンドウ ハンドルを設定しなければならない。

lFlags
要求された機能を指定する CONST_DMUS_AUDIO 列挙型のフラグ。AudioParams 型の lValidData メンバの値が 0 でない場合、この値は無視されるので、要求された機能は AudioParams の lFeatures メンバで指定する。
AudioParams
シンセサイザのパラメータを指定し、どのパラメータが設定されたかについての情報を受け取る DMUS_AUDIOPARAMS 型。 lValidData メンバが 0 である場合、デフォルトのパラメータが設定される。
DirectSound
ウェーブ出力のデフォルトで使用される、 DirectSound8 オブジェクト。省略可。

このパラメータが、NULL に設定された変数 DirectSound8 である場合、DirectSound オブジェクトが作成され、変数 DirectSound8 にはこのオブジェクトが設定される。

このパラメータが省略される場合、内部用の DirectSound8 オブジェクトが作成される。

「注意」を参照すること。

lDefaultPathType
デフォルトのオーディオパス タイプを指定する値。デフォルトのパス タイプが不要ならば 0 を指定するか、省略する。それ以外の場合は CONST_DMUSIC_STANDARD_AUDIO_PATH 列挙型のいずれかの定数を指定する。
lPChannelCount
lDefaultPathType が 0 以外である場合、または省略されていない場合、パスに割り当てるパフォーマンス チャンネル数を指定する値。

戻り値

失敗した場合は、エラーが発生する。Err.Number に次のいずれかの値が設定される。

DMUS_E_ALREADY_INITED
DMUS_E_OUTOFMEMORY

注意

このメソッドは 1 回だけ呼び出すべきである。

パフォーマンスを解放する前に、DirectMusicPerformance8.CloseDown メソッドを使ってパフォーマンスを終了しなければならない。

DirectSound8 オブジェクトが存在できるのは 1 つのプロセスにつき 1 つだけである。アプリケーションで DirectSound8 を個別に使用する場合は、DirectSound でそのオブジェクトを渡さなければならない。最初に、DSSCL_PRIORITY を DirectSound8.SetCooperativeLevel に渡して協調レベルを設定する必要がある。

現在の前面ウィンドウのハンドルを DirectSound に渡すには、hwnd パラメータに 0 を設定するとよい。ただし、初期化時にアプリケーション ウィンドウが前面にあると仮定するべきではない。最上位アプリケーション ウィンドウ ハンドルを渡すのが望ましい。

lFlags と AudioParams に設定されたパラメータは、デフォルトのオーディオパスと、これ以降に作成されるすべてのオーディオパスに適用される。


DirectMusicPerformance8.Invalidate

指定されたタイムより後のタイム スタンプを持つキュー内のすべてのメッセージをフラッシュ (解放) し、指定されたタイムから前方に向かって、すべてのセグメントのすべてのトラックにデータを再送させる。

object.Invalidate( _
  mtTime As Long, _
  flags As Long)

指定項目

object
DirectMusicPerformance8 オブジェクトを指定する。
mtTime
無効にするタイム。flags によって調整される。この値を 0 に設定すると、即座に無効になる。
flags
mtTime を小節、拍、またはグリッドのどれに揃えるかを指定する値。この値は、0 または次に示す CONST_DMUS_SEGF_FLAGS のいずれかのメンバでもよい。

DMUS_SEGF_MEASURE
DMUS_SEGF_BEAT
DMUS_SEGF_GRID

エラー コード

失敗した場合はエラーが発生し、Err.Number に DMUS_E_NO_MASTER_CLOCK が設定される。

注意

mtTime がかなり前のタイムで、そのタイムで無効化が行えない場合は、利用可能な範囲で最も早いタイムを使用する。

参照

DirectMusicPerformance8.GetQueueTime


DirectMusicPerformance8.IsPlaying

特定のセグメントまたはセグメント状態が現在スピーカから演奏されているかどうかを判別する。

object.IsPlaying( _
  segment As DirectMusicSegment8, _
  SegmentState8 As DirectMusicSegmentState8 _
) As Boolean

指定項目

object
DirectMusicPerformance8 オブジェクトを指定する。
segment
チェックする DirectMusicSegment8。NULL の場合、SegmentState8 だけをチェックする。
SegmentState8
チェックする DirectMusicSegmentState8。NULL の場合、セグメントだけをチェックする。

戻り値

このメソッドが成功し、要求したセグメントとセグメント状態のどちらかが演奏されている場合は TRUE を返す。どちらも演奏されていない場合、またはどちらか 1 つだけを要求し、それが演奏されていない場合は、FALSE を返す。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

DMUS_E_NO_MASTER_CLOCK

注意

セグメントまたはセグメント状態が実際にスピーカで演奏中である場合にのみ、TRUE が返される。DirectMusicPerformance8.PlaySegmentEx がセグメントに対して呼び出された直後でも、遅延時間があるので、FALSE が返される可能性がある。同様の理由で、すべてのメッセージが既に発信されている場合でも、セグメントが聞こえている間は、TRUE が返される。


DirectMusicPerformance8.MusicToClockTime

ミュージック タイム フォーマットの時間をクロック タイム フォーマットに変換する。

object.MusicToClockTime(mtTime As Long) As Long

指定項目

object
DirectMusicPerformance8 オブジェクトを指定する。
mtTime
変換されるミュージック タイム フォーマットのタイム。

戻り値

時間をクロック タイム単位で返す。

エラー コード

失敗した場合はエラーが発生し、Err.Number に DMUS_E_NO_MASTER_CLOCK が設定される。

注意

このメソッドは、パフォーマンスの時間ではなく、パフォーマンスの開始からのタイムのオフセットを変換する。ミュージック タイムとクロック タイムの単位の比率はテンポに依存するため、変換時には、パフォーマンスが開始されてからのテンポの変更がすべて考慮される。パフォーマンスについてマスタ テンポが設定されている場合は、同様に考慮される。

クロック タイムはミュージック タイムよりも正確であるため、クロック タイムからミュージック タイムに変換し、再びクロック タイムに変換したタイムは、元の値とは異なる可能性がある。

参照

DirectMusicPerformance8.ClockToMusicTime、クロック タイムとミュージック タイム


DirectMusicPerformance8.PlaySegmentEx

セグメントの再生を開始する。

object.PlaySegmentEx( _
  Source As Unknown, _
  lFlags As CONST_DMUS_SEGF_FLAGS, _
  StartTime As Long, _
  [From As Unknown], _
  [AudioPath As Unknown], _
) As DirectMusicSegmentState8

指定項目

object
DirectMusicPerformance8 オブジェクトを指定する。
Source
演奏する DirectMusicSegment8 オブジェクト。
lFlags
メソッドの動作を変更するフラグ。0、または CONST_DMUS_SEGF_FLAGS 列挙型の 1 つ以上の定数。
StartTime
セグメントの演奏が開始されるパフォーマンス タイム。lFlags で指定する任意の分解能境界に調整される。DMUS_SEGF_REFTIME フラグが設定されていない限り、タイムはミュージック タイムで表される。値が 0 の場合、セグメントの演奏はできる限り早く開始される。
From
新しいセグメントの開始時に演奏を停止するオプションの DirectMusicSegmentState8 または DirectMusicAudioPath8 オブジェクト。省略可。これがオーディオパスの場合は、そのオーディオパスで演奏されているすべてのセグメント状態が停止される。
AudioPath
どのオーディオパス上でセグメントを演奏するかを表す DirectMusicAudioPath8 オブジェクト。省略可。NULL を指定するか、省略する場合、セグメントはデフォルト パス上で演奏される。

戻り値

セグメントの演奏中のインスタンスを表す、DirectMusicSegmentState8 オブジェクトを返す。

エラー コード

失敗した場合は、エラーが発生する。Err.Number に次のいずれかの値が設定される。

DMUS_E_AUDIOPATH_INACTIVE
DMUS_E_AUDIOPATH_NOPORT
DMUS_E_NO_MASTER_CLOCK
DMUS_E_SEGMENT_INIT_FAILED
DMUS_E_TIME_PAST
DMUS_E_OUTOFMEMORY

注意

セグメントの長さは 250 ミリ秒 (ms) を超えているべきである。

lFlags の境界分解能は、プライマリ セグメントに関連するものである。

あるプライマリ セグメントの演奏中に、別のプライマリ セグメントを演奏するスケジュールが設定される場合、後に演奏されるセグメントに DMUS_SEGF_QUEUE フラグを設定しない限り、先に演奏されるセグメントは停止する。フラグが設定されると、後のセグメントの演奏は、先のセグメントの演奏が終わってから開始される。

セグメントの正確な開始タイムの詳細については、「セグメントのタイミング」を参照すること。テンポの変更がセグメントの開始タイムに及ぼす影響については、「クロック タイムとミュージック タイム」を参照すること。

lFlags に DMUS_SEGF_AUTOTRANSITION が指定されているときに、StartTime で演奏中のセグメントを中断する場合、このメソッドは、2 つのセグメント間のトランジションをアレンジして、それを演奏した後に Source を演奏する。

Source がセグメントの場合は、Transition で指定されたテンプレートに基づくトランジション用のセグメントがアレンジされて演奏される。

参照

セグメントの使い方、トランジションの使い方


DirectMusicPerformance8.RemoveNotificationType

前に追加された通知タイプをパフォーマンスから削除し、そのタイプの通知メッセージがそれ以降送信されないようにする。

object.RemoveNotificationType( _
    type As CONST_DMUS_NOTIFICATION_TYPE)

指定項目

object
DirectMusicPerformance8 オブジェクトを指定する。
type
通知メッセージが送信されないイベントのタイプ。指定可能な値については、「CONST_DMUS_NOTIFICATION_TYPE」を参照すること。

エラー コード

失敗した場合はエラーが発生し、Err.Number に DMUS_E_INVALIDARG が設定される。

参照

DirectMusicPerformance8.AddNotificationType


DirectMusicPerformance8.Reset

ポートをリセットする。

object.Reset(resetflags As Long)

指定項目

object
DirectMusicPerformance8 オブジェクトを指定する。
resetflags
フラグ。この値が 0 の場合、GMReset が実行される。この値が 1 の場合、ポートをいったん閉じ、再度開くことによって、リセットされる。

エラー コード

失敗した場合はエラーが発生し、Err.Number が設定される。


DirectMusicPerformance8.SendCurvePMSG

カーブに関する情報を保持するパフォーマンス メッセージを送信する。

object.SendCurvePMSG( _
  lTime As Long, _
  flags As Long, _
  channel As Long, _
  msg As DMUS_CURVE_PMSG)

指定項目

object
DirectMusicPerformance8 オブジェクトを指定する。
lTime
メッセージが演奏されるタイム。flags に DMUS_PMSGF_REFTIME を指定しない限り、このタイムはミュージック タイムで表される。
flags
メッセージ処理の方法とタイムを変更するフラグ。「CONST_DMUS_PMSGF_FLAGS」を参照すること。
channel
メッセージの送信先となるパフォーマンス チャンネル。複数のチャンネルにメッセージを送信するには、CONST_DMUS_PCHANNEL 列挙型のメンバの 1 つを使用する。
msg
カーブに関する情報を含む DMUS_CURVE_PMSG 型。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

DMUS_E_NO_MASTER_CLOCK
DMUS_E_ALREADY_SENT
DMUS_E_INVALIDARG

注意

メッセージのタイムが 0、flags パラメータに DMUS_PMSGF_REFTIME が設定されている場合は、メッセージが挿入されて即座に送り出される。

参照

カーブ


DirectMusicPerformance8.SendMIDIPMSG

その他のメソッドによって処理されない MIDI チャンネル メッセージに関する情報を含むパフォーマンス メッセージを送信する。

object.SendMIDIPMSG( _
    lTime As Long, _
    flags As Long, _
    channel As Long, _
    status As Byte, _
    byte1 As Byte, _
    byte2 As Byte)

指定項目

object
DirectMusicPerformance8 オブジェクトを指定する。
lTime
メッセージが演奏されるタイム。flags に DMUS_PMSGF_REFTIME を指定しない限り、このタイムはミュージック タイムで表される。
flags
メッセージ処理の方法とタイムを変更するフラグ。「CONST_DMUS_PMSGF_FLAGS」を参照すること。
channel
メッセージの送信先となるパフォーマンス チャンネル。複数のチャンネルにメッセージを送信するには、CONST_DMUS_PCHANNEL 列挙型のメンバの 1 つを使用する。
status
スタンダード MIDI のステータス バイト。「注意」を参照すること。
byte1
先頭のデータ バイト。これを必要としない MIDI メッセージでは無視される。
byte2
2 番目のデータ バイト。これを必要としない MIDI メッセージでは無視される。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

DMUS_E_NO_MASTER_CLOCK
DMUS_E_ALREADY_SENT
DMUS_E_INVALIDARG

注意

メッセージのタイムが 0、flags パラメータに DMUS_PMSGF_REFTIME が設定されている場合は、メッセージが挿入されて即座に送り出される。

チャンネルは別のパラメータ内で指定されるため、スタンダード MIDI メッセージの場合とは異なり、status の下位 4 ビットにはチャンネル番号が含まれない。したがって、status はノートオフの場合に &H80、ノートオンの場合に &H90 などとなる。その他のステータス バイトについては、MIDI 規格を参照すること。


DirectMusicPerformance8.SendNotePMSG

ノートに関する情報を保持するパフォーマンス メッセージを送信する。

object.SendNotePMSG( _
  lTime As Long, _
  flags As Long, _
  channel As Long, _
  msg As DMUS_NOTE_PMSG)

指定項目

object
DirectMusicPerformance8 オブジェクトを指定する。
lTime
メッセージが演奏されるタイム。flags に DMUS_PMSGF_REFTIME を指定しない限り、このタイムはミュージック タイムで表される。lTime の値が 0 であり、flags に DMUS_PMSGF_REFTIME が設定されている場合、メッセージは即時に演奏される。
flags
メッセージ処理の方法とタイムを変更するフラグ。「CONST_DMUS_PMSGF_FLAGS」を参照すること。
channel
メッセージの送信先となるパフォーマンス チャンネル。複数のチャンネルにメッセージを送信するには、CONST_DMUS_PCHANNEL 列挙型のメンバの 1 つを使用する。
msg
ノートに関する情報を含む DMUS_NOTE_PMSG 型。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

DMUS_E_NO_MASTER_CLOCK
DMUS_E_ALREADY_SENT
DMUS_E_INVALIDARG

注意

次のサンプル コードでは、perf が DirectMusicPerformance8 オブジェクトであり、メッセージを送信して、直ちに中間の C を演奏する。

Dim note As DMUS_NOTE_PMSG

note.midiValue = 60
note.mtDuration = 500
note.flags = DMUS_NOTEF_NOTEON
note.velocity = 127
Call perf.SendNotePMSG(0, DMUS_PMSGF_REFTIME, 1, note)


DirectMusicPerformance8.SendPatchPMSG

MIDI パッチ変更に関する情報を保持するパフォーマンス メッセージを送信する。

object.SendPatchPMSG( _
  lTime As Long, _
  flags As Long, _
  channel As Long, _
  instrument As Byte, _
  byte1 As Byte, _
  byte2 As Byte)

指定項目

object
DirectMusicPerformance8 オブジェクトを指定する。
lTime
メッセージが演奏されるタイム。flags に DMUS_PMSGF_REFTIME を指定しない限り、このタイムはミュージック タイムで表される。
flags
メッセージ処理の方法とタイムを変更するフラグ。「CONST_DMUS_PMSGF_FLAGS」を参照すること。
channel
メッセージの送信先となるパフォーマンス チャンネル。複数のチャンネルにメッセージを送信するには、CONST_DMUS_PCHANNEL 列挙型のメンバの 1 つを使用する。
instrument
チャンネルに割り当てるパッチ番号。
byte1
バンク セレクトの上位バイト。
byte2
バンク セレクトの下位バイト。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

DMUS_E_NO_MASTER_CLOCK
DMUS_E_ALREADY_SENT
DMUS_E_INVALIDARG

注意

メッセージのタイムが 0、flags パラメータに DMUS_PMSGF_REFTIME が設定されている場合は、メッセージが挿入されて即座に送り出される。


DirectMusicPerformance8.SendTempoPMSG

テンポ変更に関する情報を保持するパフォーマンス メッセージを送信する。

object.SendTempoPMSG( _
  lTime As Long, _
  flags As Long, _
  tempo As Double)

指定項目

object
DirectMusicPerformance8 オブジェクトを指定する。
lTime
メッセージが演奏されるタイム。flags に DMUS_PMSGF_REFTIME を指定しない限り、このタイムはミュージック タイムで表される。
flags
メッセージ処理の方法とタイムを変更するフラグ。「CONST_DMUS_PMSGF_FLAGS」を参照すること。
tempo
新しいテンポ。1 分あたりの拍数で表す。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

DMUS_E_NO_MASTER_CLOCK
DMUS_E_ALREADY_SENT
DMUS_E_INVALIDARG

注意

メッセージのタイムが 0、flags パラメータに DMUS_PMSGF_REFTIME が設定されている場合は、メッセージが挿入されて即座に送り出される。


DirectMusicPerformance8.SendTimeSigPMSG

拍子記号に関する情報を保持するパフォーマンス メッセージを送信する。

object.SendTimeSigPMSG( _
  lTime As Long, _
  flags As Long, _
  timeSig As DMUS_TIMESIGNATURE)

指定項目

object
DirectMusicPerformance8 オブジェクトを指定する。
lTime
メッセージが演奏されるタイム。flags に DMUS_PMSGF_REFTIME を指定しない限り、このタイムはミュージック タイムで表される。
flags
メッセージ処理の方法とタイムを変更するフラグ。「CONST_DMUS_PMSGF_FLAGS」を参照すること。
timeSig
拍子記号に関する情報を含む DMUS_TIMESIGNATURE 型。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

DMUS_E_NO_MASTER_CLOCK
DMUS_E_ALREADY_SENT
DMUS_E_INVALIDARG

注意

メッセージのタイムが 0、flags パラメータに DMUS_PMSGF_REFTIME が設定されている場合は、メッセージが挿入されて即座に送り出される。


DirectMusicPerformance8.SendTransposePMSG

転調を開始するためのパフォーマンス メッセージを送信する。

object.SendTransposePMSG( _
  lTime As Long, _
  flags As Long, _
  channel As Long, _
  transpose As Integer)

指定項目

object
DirectMusicPerformance8 オブジェクトを指定する。
lTime
メッセージが演奏されるタイム。flags に DMUS_PMSGF_REFTIME を指定しない限り、このタイムはミュージック タイムで表される。
flags
メッセージ処理の方法とタイムを変更するフラグ。「CONST_DMUS_PMSGF_FLAGS」を参照すること。
channel
転調が行われるパフォーマンス チャンネル。複数のチャンネルにメッセージを送信するには、CONST_DMUS_PCHANNEL 列挙型のメンバの 1 つを使用する。
transpose
ノートが転置される半音の数。負の値であってもよい。ノートの転調によって、スタンダード MIDI の範囲 0 ～ 127 より外側に達した場合は、そのノートは演奏されない。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

DMUS_E_NO_MASTER_CLOCK
DMUS_E_ALREADY_SENT
DMUS_E_INVALIDARG

注意

メッセージのタイムが 0、flags パラメータに DMUS_PMSGF_REFTIME が設定されている場合は、メッセージが挿入されて即座に送り出される。


DirectMusicPerformance8.SetBumperLength

メッセージがポート バッファに置かれてから、ポートによる処理が開始されるまでの時間を設定する。

object.SetBumperLength(lMilliSeconds As Long)

指定項目

object
DirectMusicPerformance8 オブジェクトを指定する。
lMilliSeconds
バンパーの希望の長さ。ミリ秒単位で指定する。デフォルト値は 50 である。

エラー コード

失敗した場合はエラーが発生し、Err.Number が設定される。

参照

DirectMusicPerformance8.GetBumperLength、DirectMusicPerformance8.SetPrepareTime


DirectMusicPerformance8.SetDefaultAudioPath

パフォーマンスのデフォルト オーディオパスを設定してアクティブにする。

object.SetDefaultAudioPath( _
  AudioPath As DirectMusicAudioPath8)

指定項目

object
DirectMusicPerformance8 オブジェクトを指定する。
AudioPath
デフォルトのオーディオパスを指定する DirectMusicAudioPath8 オブジェクト。

エラー コード

失敗した場合は、エラーが発生する。Err.Number に次のいずれかの値が設定される。

DMUS_E_INVALIDARG
DMUS_E_AUDIOPATHS_NOT_VALID
DMUS_E_NOT_INIT


DirectMusicPerformance8.SetMasterAutoDownload

音色の自動ダウンロードのオンとオフを切り替える。

object.SetMasterAutoDownload(b As Boolean)

指定項目

object
DirectMusicPerformance8 オブジェクトを指定する。
b
自動ダウンロードをオンにする場合は TRUE、オフにする場合は FALSE を指定する。デフォルト値は FALSE である。

エラー コード

失敗した場合はエラーが発生し、Err.Number が設定される。

参照

DirectMusicPerformance8.GetMasterAutoDownload、DirectMusicSegment8.SetAutoDownloadEnable


DirectMusicPerformance8.SetMasterGrooveLevel

パフォーマンス内のすべてのグルーブ レベルに加算される値を設定する。

object.SetMasterGrooveLevel(level As Integer)

指定項目

object
DirectMusicPerformance8 オブジェクトを指定する。
level
グルーブ レベルに加算される値。－ 99 ～ 99の範囲で指定する。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

DMUS_E_FAIL
DMUS_E_OUTOFMEMORY

注意

調整されたグルーブ レベルは、常に 1 ～ 100 の範囲にある。

参照

DirectMusicPerformance8.GetMasterGrooveLevel


DirectMusicPerformance8.SetMasterTempo

テンポに適用されるスケーリング係数を設定する。

object.SetMasterTempo(tempo As Single)

指定項目

object
DirectMusicPerformance8 オブジェクトを指定する。
tempo
目的のマスタ テンポ。0.01 ～ 100.0 の範囲で指定する。

エラー コード

失敗した場合はエラーが発生し、Err.Number が設定される。

注意

マスタ テンポにはデフォルトで 1 が設定される。値が 0.5 の場合テンポは半分になり、2.0 の場合は 2 倍になる。

参照

DirectMusicPerformance8.GetMasterTempo


DirectMusicPerformance8.SetMasterVolume

パフォーマンスのマスタ ボリュームを調整する。

object.SetMasterVolume(vol As Long)

指定項目

object
DirectMusicPerformance8 オブジェクトを指定する。
vol
マスタ ボリュームの調整。1/100 dB (デシベル) 単位で指定する。

エラー コード

失敗した場合はエラーが発生し、Err.Number が設定される。

注意

マスタ ボリュームは、パフォーマンス全体のデフォルト ボリュームに適用される増幅係数または減衰係数である。設定できる値の範囲はポートによって決まる。デフォルトのソフトウェア シンセサイザの場合、使用可能な範囲は ＋ 20 ～ － 200 dB であるが、実用的な範囲は ＋ 10 ～ － 100 dB である。

参照

DirectMusicPerformance8.GetMasterVolume


DirectMusicPerformance8.SetNotificationHandle

通知のイベント ハンドルを設定する。シグナルが送信されたら、アプリケーションは DirectMusicPerformance8.GetNotificationPMsg メソッドを呼び出して、通知イベントを取得しなければならない。

object.SetNotificationHandle(hnd As Long)

指定項目

object
DirectMusicPerformance8 オブジェクトを指定する。
hnd
イベント ハンドル。既存のハンドルを消去する場合は 0 を指定する。

参照

DirectXEvent8


DirectMusicPerformance8.SetPrepareTime

メッセージが準備されてから、処理され、スピーカから聞こえるまでのだいたいの時間を設定する。

object.SetPrepareTime(lMilliSeconds As Long)

指定項目

object
DirectMusicPerformance8 オブジェクトを指定する。
lMilliSeconds
準備時間の長さ。ミリ秒単位で指定する。デフォルト値は 1,000 である。

エラー コード

失敗した場合はエラーが発生し、Err.Number が設定される。

参照

DirectMusicPerformance8.GetPrepareTime、DirectMusicPerformance8.SetBumperLength、準備時間


DirectMusicPerformance8.StopEx

オブジェクトの再生を停止する。

object.StopEx( _
  ObjectToStop As Unknown, _
  lStopTime As Long, _
  lFlags As Long)

指定項目

object
DirectMusicPerformance8 オブジェクトを指定する。
ObjectToStop
停止する DirectMusicSegment8、DirectMusicSegmentState8、または DirectMusicAudioPath8 の各オブジェクト。
lStopTime
停止するタイム。このタイムが過去のタイムである場合や、値として 0 を指定した場合は、オブジェクトの演奏が即座に停止される。
lFlags
演奏の停止タイムを指定するフラグ。境界は現在のプライマリ セグメントに関連する。このパラメータが 0 である場合は、即時に停止される。CONST_DMUS_SEGF_FLAGS 列挙型のうち、以下の定数のいずれか、または DMUS_SEGF_REFTIME に別のフラグを組み合わせることができる。
DMUS_SEGF_BEAT
次の拍境界で、または lStopTime の後に停止する。
DMUS_SEGF_DEFAULT
デフォルト境界で停止する。
DMUS_SEGF_GRID
次のグリッド境界で、または lStopTime の後に停止する。
DMUS_SEGF_MEASURE
次の小節境界で、または lStopTime の後に停止する。
DMUS_SEGF_REFTIME
i64StopTime の値は基準タイムである。
DMUS_SEGF_SEGMENTEND
セグメントの終端で停止する。
DMUS_SEGF_MARKER
次のマーカーで停止する。

エラー コード

失敗した場合は、エラーが発生する。

注意

セグメントを停止すると、演奏中のすべてのインスタンスが停止する。

参照

DirectMusicPerformance8.PlaySegmentEx


DirectMusicSegment8

1 つのミュージック ピース、またはテンプレートを表す。

セグメントは通常、DirectMusicLoader8.LoadSegment および DirectMusicLoader8.LoadSegmentFromResource を呼び出すことでロードされる。また、DirectMusicComposer8 オブジェクトのメソッドを使ってミュージック要素からアレンジしたり、DirectMusicSegment8.Clone メソッドを使って既存のセグメントから作成したりすることもできる。

DirectMusicSegment8 オブジェクトのメソッドは、以下のグループにまとめることができる。

タイミングとループ | GetLength
 | GetLoopPointStart
 | GetLoopPointEnd
 | GetRepeats
 | GetStartPoint
 | SetLength
 | SetLoopPoints
 | SetRepeats
 | SetStartPoint
音色 | ConnectToCollection
 | Download
 | Unload
パラメータ | SetAutoDownloadEnable
 | SetStandardMidiFile
 | SetTempoEnable
 | SetTimeSigEnable
その他 | Clone
 | GetAudioPathConfig
 | GetChordMap
 | GetName
 | GetStyle


DirectMusicSegment8.Clone

セグメントのすべてまたはパートのコピーを作成する。

object.Clone( _
  mtStart As Long, _
  mtEnd As Long _
) As DirectMusicSegment8

指定項目

object
DirectMusicSegment8 オブジェクトを指定する。
mtStart
複製開始パート。ミュージック タイムで指定する。0 未満の場合や、セグメントの長さを超える場合は、0 が使用される。
mtEnd
複製終了パート。ミュージック タイムで指定する。この値がセグメントの最後を超える場合は、セグメントの最後までコピーされる。0 または mtStart 未満の場合も、最後までコピーされる。

戻り値

DirectMusicSegment8 オブジェクトを返す。

エラー コード

失敗した場合はエラーが発生し、Err.Number に DMUS_E_OUTOFMEMORY が設定される。

注意

開始ポイント、ループ ポイント、反復回数、デフォルトのオーディオパスなど、オリジナルのセグメントのプロパティがクローンにコピーされる。

スタイルベースのセグメントは、mtStart が 0 より大きい場合、小節境界上になければならない。


DirectMusicSegment8.ConnectToCollection

セグメントを DLS 音色コレクションに関連付ける。音色コレクションは DirectMusicSegment8.Download メソッドが呼び出されるときにダウンロードされる。

object.ConnectToCollection(c As DirectMusicCollection8)

指定項目

object
DirectMusicSegment8 オブジェクトを指定する。
c
セグメントで使用される音色を表す DirectMusicCollection8 オブジェクト。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

DMUS_E_SET_UNSUPPORTED
DMUS_E_TRACK_NOT_FOUND

注意

デフォルトでは、Gm.dls ファイル内の General MIDI コレクションが、セグメントに接続される。このメソッドを呼び出す必要があるのは、セグメントをカスタムな音色を使って演奏するときだけである。


DirectMusicSegment8.Download

パフォーマンスまたはオーディオパスにバンドおよびウェーブ データをダウンロードする。

object.Download(downloadpath As Unknown)

指定項目

object
DirectMusicSegment8 オブジェクトを指定する。
downloadpath
音色のダウンロード先となる DirectMusicAudioPath8 オブジェクトまたは DirectMusicPerformance8 オブジェクト。

エラー コード

失敗するとエラーが発生する。Err.Number に次のいずれかの値が設定される。

DMUS_E_NOT_FOUND
DMUS_E_TRACK_NOT_FOUND

注意

セグメント内のすべてのバンドおよびウェーブ データがダウンロードされる。

セグメント オブジェクトがスコープ外に出る前に、常に DirectMusicSegment8.Unload を呼び出す。そうでない場合、セグメント オブジェクトは破棄される。

参照

DirectMusicSegment8.ConnectToCollection、DirectMusicSegment8.Unload、DirectMusicSegment8.SetAutoDownloadEnable


DirectMusicSegment8.GetAudioPathConfig

セグメントのオーディオパス構成を表すオブジェクトを取得する。

object.GetAudioPathConfig() As Unknown

指定項目

object
DirectMusicSegment8 オブジェクトを指定する。

戻り値

オーディオパス構成を表すオブジェクトを返す。このオブジェクトは、IUnknown 型の変数で取得することができ、DirectMusicPerformance8.CreateAudioPath に渡される。

エラー コード

失敗した場合は、エラーが発生する。


DirectMusicSegment8.GetChordMap

コード マップを取得する。

object.GetChordMap( _
  lTrack As Long, _
  mtTime As Long, _
  mtUntil As Long _
) As DirectMusicChordMap8

指定項目

object
DirectMusicSegment8 オブジェクトを指定する。
lTrack
コード マップ トラックのインデックス。トラックを検索する場合は、&H80000000 を指定する。
mtTime
コード マップを取得するタイム。
mtUntil
コード マップが無効になるタイムを受け取る変数。mtTime からの相対タイムとして表される。

戻り値

DirectMusicChordMap8 オブジェクトを返す。

エラー コード

失敗した場合は、エラーが発生する。


DirectMusicSegment8.GetLength

セグメントの長さを取得する。

object.GetLength() As Long

指定項目

object
DirectMusicSegment8 オブジェクトを指定する。

戻り値

セグメントの長さをミュージック タイム単位で返す。

エラー コード

失敗した場合はエラーが発生し、Err.Number が設定される。

注意

ウェーブ ファイルで作成されたセグメントに対して、このメソッドは常に 1 を返す。

参照

DirectMusicSegment8.SetLength


DirectMusicSegment8.GetLoopPointEnd

反復セクションが終了するセグメント内のポイントを取得する。

object.GetLoopPointEnd() As Long

指定項目

object
DirectMusicSegment8 オブジェクトを指定する。

戻り値

ループの終了ポイントをミュージック タイムで返す。この値が 0 の場合、セグメント全体がループする。

エラー コード

失敗した場合はエラーが発生し、Err.Number が設定される。

注意

DirectMusicSegment8.SetRepeats メソッドを使用して反復回数が 1 以上に設定されない限り、このセクションは繰り返されない。デフォルトでは、セグメント全体が繰り返される。

参照

DirectMusicSegment8.GetLoopPointStart、DirectMusicSegment8.SetLoopPoints、DirectMusicSegment8.GetRepeats


DirectMusicSegment8.GetLoopPointStart

反復セクションが開始するセグメント内のポイントを取得する。

object.GetLoopPointStart() As Long

指定項目

object
DirectMusicSegment8 オブジェクトを指定する。

戻り値

ループの開始ポイントをミュージック タイムで返す。

エラー コード

失敗した場合はエラーが発生し、Err.Number が設定される。

注意

DirectMusicSegment8.SetRepeats メソッドを使用して反復回数が 1 以上に設定されない限り、このセクションは繰り返されない。デフォルトでは、セグメント全体が繰り返される。

参照

DirectMusicSegment8.GetLoopPointEnd、DirectMusicSegment8.SetLoopPoints、DirectMusicSegment8.GetRepeats


DirectMusicSegment8.GetName

セグメントの内部名を取得する。

object.GetName() As String

指定項目

object
DirectMusicSegment8 オブジェクトを指定する。

戻り値

セグメントの内部名を返す。セグメントが内部名を持たない場合は、ファイル名が返される。

エラー コード

失敗した場合は、エラーが発生する。


DirectMusicSegment8.GetRepeats

セグメントのループ部分に設定されている反復回数を取得する。

object.GetRepeats() As Long

指定項目

object
DirectMusicSegment8 オブジェクトを指定する。

戻り値

ループ部分を反復する回数を返す。

エラー コード

失敗した場合はエラーが発生し、Err.Number が設定される。

参照

DirectMusicSegment8.SetRepeats、DirectMusicSegment8.SetLoopPoints、DirectMusicSegment8.GetLoopPointStart、DirectMusicSegment8.GetLoopPointEnd、DirectMusicSegmentState8.GetRepeats


DirectMusicSegment8.GetStartPoint

セグメントが DirectMusicPerformance8.PlaySegmentEx メソッドに応答して演奏を開始するポイントを取得する。

object.GetStartPoint() As Long

指定項目

object
DirectMusicSegment8 オブジェクトを指定する。

戻り値

セグメントの開始ポイントをミュージック タイムで返す。

エラー コード

失敗した場合はエラーが発生し、Err.Number が設定される。

参照

DirectMusicSegment8.SetStartPoint


DirectMusicSegment8.GetStyle

スタイルを取得する。

object.GetStyle( _
  lTrack As Long, _
  mtTime As Long, _
  mtUntil As Long _
) As DirectMusicStyle8

指定項目

object
DirectMusicSegment8 オブジェクトを指定する。
lTrack
スタイル トラックのインデックス。トラックを検索する場合は、&H80000000 を指定する。
mtTime
スタイルを取得するタイム。
mtUntil
スタイルが無効になるタイムを受け取る変数。mtTime からの相対タイムとして表される。

戻り値

DirectMusicStyle8 オブジェクトを返す。

エラー コード

失敗した場合は、エラーが発生する。


DirectMusicSegment8.SetAutoDownloadEnable

セグメントに関連付けられたコレクション内の音色を、自動ダウンロードおよび自動アンロードする機能の、オンとオフを切り替える。

object.SetAutoDownloadEnable(b As Boolean)

指定項目

object
DirectMusicSegment8 オブジェクトを指定する。
b
自動ダウンロードを有効にする場合は TRUE、無効にする場合は FALSE を指定する。

注意

自動ダウンロードはデフォルトで無効になっている。自動ダウンロードを有効にすると、音色はセグメントの演奏時に自動的にダウンロードされ、演奏を停止するとアンロードされる。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

DMUS_E_SET_UNSUPPORTED
DMUS_E_TRACK_NOT_FOUND

参照

DirectMusicSegment8.Download


DirectMusicSegment8.SetLength

セグメントの長さを設定する。

object.SetLength(mtLength As Long)

指定項目

object
DirectMusicSegment8 オブジェクトを指定する。
mtLength
セグメントの希望の長さ。ミュージック タイムで指定する。0 より大きい値でなければならない。

エラー コード

失敗した場合はエラーが発生し、Err.Number に DMUS_E_OUT_OF_RANGE が設定される。

注意

ほとんどの場合、アプリケーションは長さを設定する必要はない。セグメントのロード時に自動的に設定されるためである。ただし、このメソッドを使って、セグメントの長さを短くすることができる。

参照

DirectMusicSegment8.GetLength


DirectMusicSegment8.SetLoopPoints

セグメント内のループ部分の開始ポイントと終了ポイントを設定する。ループの反復回数は DirectMusicSegment8.SetRepeats メソッドによって設定される。

object.SetLoopPoints(mtStart As Long, mtEnd As Long)

指定項目

object
DirectMusicSegment8 オブジェクトを指定する。
mtStart
ループの開始ポイント。ミュージック タイムで指定する。
mtEnd
ループの終了ポイント。ミュージック タイムで指定する。値 0 は、セグメント全体をループすることを意味する。

エラー コード

失敗した場合はエラーが発生し、Err.Number に DMUS_E_OUT_OF_RANGE が設定される。

注意

セグメントの演奏時には、開始タイムから mtEnd まで演奏し、mtStart にループする。次に、ループ部分を DirectMusicSegment8.SetRepeats によって設定される回数だけ反復し、最後まで演奏する。

デフォルト値は、最初から最後までセグメント全体をループするように設定されている。

mtStart の値がセグメントの長さ以上の場合、または mtEnd の値がセグメントの長さを超える場合、メソッドは失敗する。mtEnd が 0 の場合、mtStart も 0 でなければならない。

このメソッドは、このセグメントから作成された、現在演奏中のセグメント状態に影響を及ぼすことはない。

再利用されるセグメントは、内部キャッシュからロードされる可能性もある。その場合、そのセグメントのループ ポイントは、最後に設定された値と同じ値を持つ。再び演奏する可能性のあるセグメントを解放する前には、ループ ポイントを 0 にリセットするとよい。

参照

DirectMusicSegment8.GetLoopPointStart、DirectMusicSegment8.GetLoopPointEnd、DirectMusicSegment8.SetRepeats


DirectMusicSegment8.SetRepeats

セグメントのループ部分の反復回数を設定する。

object.SetRepeats(lRepeats As Long)

指定項目

object
DirectMusicSegment8 オブジェクトを指定する。
lRepeats
反復回数。

エラー コード

失敗した場合はエラーが発生し、Err.Number が設定される。

参照

DirectMusicSegment8.GetRepeats、DirectMusicSegment8.SetLoopPoints


DirectMusicSegment8.SetStandardMidiFile

セグメントが、DirectMusic 用に特別にオーサリングされたものではなく、スタンダード MIDI ファイルに基づいていることを DirectMusic に通知する。このメソッドを呼び出すと、セグメントの演奏時に特定のイベントが適切に処理される。

object.SetStandardMidiFile()

指定項目

object
DirectMusicSegment8 オブジェクトを指定する。

エラー コード

失敗した場合はエラーが発生し、Err.Number が設定される。

注意

このメソッドは、音色をダウンロードする前に呼び出さなければならない。


DirectMusicSegment8.SetStartPoint

セグメントが DirectMusicPerformance8.PlaySegmentEx メソッドの呼び出しに応答して演奏を開始するポイントを設定する。

object.SetStartPoint(mtStart As Long)

指定項目

object
DirectMusicSegment8 オブジェクトを指定する。
mtStart
セグメントの演奏開始ポイント。ミュージック タイムで指定する。0 以上で、セグメントの長さより小さくなければならない。

エラー コード

失敗した場合はエラーが発生し、Err.Number に DMUS_E_OUT_OF_RANGE が設定される。

注意

デフォルトの開始ポイントは 0 であり、セグメントの先頭から開始することを意味する。

このメソッドは、このセグメントから作成された、現在演奏中のセグメント状態に影響を及ぼすことはない。

再利用されるセグメントは、内部キャッシュからロードされる可能性もある。その場合、そのセグメントの開始ポイントは、最後に設定された値と同じ値を持つ。再び演奏する可能性のあるセグメントを解放する前には、開始ポイントを 0 にリセットするとよい。

参照

DirectMusicSegment8.GetStartPoint、DirectMusicSegmentState8.GetStartPoint、DirectMusicSegment8.SetLoopPoints


DirectMusicSegment8.SetTempoEnable

セグメントのテンポ メッセージを有効または無効にする。

object.SetTempoEnable(b As Boolean)

指定項目

object
DirectMusicSegment8 オブジェクトを指定する。
b
テンポ メッセージを有効にする場合は TRUE、無効にする場合は FALSE を指定する。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

DMUS_E_SET_UNSUPPORTED
DMUS_E_TRACK_NOT_FOUND


DirectMusicSegment8.SetTimeSigEnable

セグメントの拍子記号メッセージを有効または無効にする。

object.SetTempoEnable(b As Boolean)

指定項目

object
DirectMusicSegment8 オブジェクトを指定する。
b
拍子記号メッセージを有効にする場合は TRUE、無効にする場合は FALSE を指定する。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

DMUS_E_SET_UNSUPPORTED
DMUS_E_TRACK_NOT_FOUND


DirectMusicSegment8.Unload

DirectMusicSegment8.Download メソッドによってポートにダウンロードされた音色をアンロードする。

object.Unload(downloadpath As Unknown)

指定項目

object
DirectMusicSegment8 オブジェクトを指定する。
downloadpath
音色のアンロード元となる DirectMusicAudioPath8 オブジェクトまたは DirectMusicPerformance8 オブジェクト。

エラー コード

失敗した場合はエラーが発生し、Err.Number が設定される。

参照

DirectMusicSegment8.SetAutoDownloadEnable


DirectMusicSegmentState8

セグメントの演奏中のインスタンスを表す。DirectMusicPerformance8.PlaySegmentEx メソッドを呼び出すと、DirectMusicSegmentState8 オブジェクトが作成され、アプリケーションはそのインスタンスに関する情報を取得できるようになる。このオブジェクトを DirectMusicPerformance8 のメソッドに渡して、セグメントのインスタンスが演奏中であるかどうかを判別したり、それを停止したりすることもできる。

このクラスは、以下のグループにまとめることができる。

情報 | GetRepeats
 | GetSeek
 | GetSegment
 | GetStartPoint
 | GetStartTime

参照

DirectMusicPerformance8.GetSegmentState


DirectMusicSegmentState8.GetRepeats

セグメントのループ部分に設定されている反復回数を返す。

object.GetRepeats() As Long

指定項目

object
DirectMusicSegmentState8 オブジェクトを指定する。

戻り値

反復回数を返す。値 0 は、そのセグメント全体を 1 回だけ演奏し、反復する部分がないことを意味する。

エラー コード

失敗した場合はエラーが発生し、Err.Number が設定される。

参照

DirectMusicSegment8.SetRepeats


DirectMusicSegmentState8.GetSeek

セグメント状態内のシーク ポインタを取得する。シーク ポインタは、メッセージが生成されたセグメント内の最後のポイントの直後にある。

object.GetSeek() As Long

指定項目

object
DirectMusicSegmentState8 オブジェクトを指定する。

戻り値

シーク ポインタをミュージック タイム形式で返す。

エラー コード

失敗した場合はエラーが発生し、Err.Number が設定される。

注意

セグメントを停止すると、既に送信されたものの、ポート バッファのキューにまだ入れられていないメッセージは、フラッシュ (解放) される。したがって、セグメントを停止し、最後のシーク ポインタで再開すると、一部のノートが失われる。


DirectMusicSegmentState8.GetSegment

このセグメント状態を所有するセグメントを表すオブジェクトを返す。

object.GetSegment() As DirectMusicSegment8

指定項目

object
DirectMusicSegmentState8 オブジェクトを指定する。

戻り値

DirectMusicSegment8 オブジェクトを返す。

エラー コード

失敗した場合はエラーが発生し、Err.Number が設定される。


DirectMusicSegmentState8.GetStartPoint

演奏の開始に使われた、またはこれから使われるセグメントのオフセットを返す。

object.GetStartPoint() As Long

指定項目

object
DirectMusicSegmentState8 オブジェクトを指定する。

戻り値

このセグメント状態の開始ポイントをミュージック タイム形式で返す。このセグメント状態を作成してから、セグメントの開始ポイントを変更した場合、この戻り値は、DirectMusicSegment8.GetStartPoint が返す値とは異なる。演奏中のセグメントの異なるインスタンスは、それぞれ異なる開始ポイントを持つことができる。

エラー コード

失敗した場合はエラーが発生し、Err.Number が設定される。

参照

DirectMusicSegment8.SetStartPoint、DirectMusicSegmentState8.GetStartTime


DirectMusicSegmentState8.GetStartTime

セグメントが演奏された、またはこれから演奏される演奏タイムを取得する。

object.GetStartTime() As Long

指定項目

object
DirectMusicSegmentState8 オブジェクトを指定する。

戻り値

セグメントのこのインスタンスの開始タイムをミュージック タイムで返す。

エラー コード

失敗した場合はエラーが発生し、Err.Number に DMUS_E_BUFFER_EMPTY が設定される。

注意

セグメントの演奏が開始ポイント以外のほかのポイントから開始された場合、このメソッドが返す値から、DirectMusicSegmentState8.GetStartPoint が返すタイムを引くことによって、このセグメントの開始タイムを取得することができる。

参照

DirectMusicSegment8.SetStartPoint、DirectMusicSegment8.GetStartPoint、DirectMusicSegmentState8.GetStartPoint


DirectMusicStyle8

スタイルを表す。スタイルとは、パターンや音色など、音楽データの集合体である。

このオブジェクトは通常、DirectMusicLoader8.LoadStyle メソッドや DirectMusicLoader8.LoadStyleFromResource メソッドを使って取得する。また、現在の制御セグメントがスタイルに基づいている場合は、DirectMusicPerformance8.GetStyle メソッドを使って、パフォーマンスから取得することもできる。

DirectMusicStyle8 クラスのメソッドは、以下のグループにまとめることができる。

バンド | GetBand
 | GetBandCount
 | GetBandName
 | GetDefaultBand
モチーフ | GetMotif
 | GetMotifCount
 | GetMotifName
時間 | GetTempo
 | GetTimeSignature


DirectMusicStyle8.GetBand

バンド オブジェクトを名前で取得する。

object.GetBand(name As String) As DirectMusicBand8

指定項目

object
DirectMusicStyle8 オブジェクトを指定する。
name
スタイルの作成者によってバンドに割り当てられた名前。

戻り値

DirectMusicBand8 オブジェクトを返す。

エラー コード

失敗した場合はエラーが発生し、Err.Number に DMUS_E_FAIL が設定される。

参照

DirectMusicStyle8.GetBandName、DirectMusicStyle8.GetDefaultBand


DirectMusicStyle8.GetBandCount

スタイル内で利用可能なバンド数を取得する。

object.GetBandCount() As Long

指定項目

object
DirectMusicStyle8 オブジェクトを指定する。

戻り値

バンド数を返す。

エラー コード

失敗した場合はエラーが発生し、Err.Number が設定される。

参照

DirectMusicStyle8.GetBand、DirectMusicStyle8.GetBandName


DirectMusicStyle8.GetBandName

スタイル内のバンドの名前を取得する。

object.GetBandName(index As Long) As String

指定項目

object
DirectMusicStyle8 オブジェクトを指定する。
index
スタイル内のバンドのインデックス。1 ～ DirectMusicStyle8.GetBandCount が返す値の範囲で指定する。

戻り値

スタイルの作成者によってバンドに割り当てられた名前を返す。

エラー コード

失敗した場合はエラーが発生し、Err.Number が設定される。

参照

DirectMusicStyle8.GetBand


DirectMusicStyle8.GetDefaultBand

スタイルのデフォルト バンドを取得する。

object.GetDefaultBand() As DirectMusicBand8

指定項目

object
DirectMusicStyle8 オブジェクトを指定する。

戻り値

DirectMusicBand8 オブジェクトを返す。

エラー コード

失敗した場合はエラーが発生し、Err.Number が設定される。

参照

DirectMusicStyle8.GetBand


DirectMusicStyle8.GetMotif

指定したモチーフを含むセグメントを作成する。

object.GetMotif(name As String) As DirectMusicSegment8

指定項目

object
DirectMusicStyle8 オブジェクトを指定する。
name
スタイルの作成者によってモチーフに割り当てられた名前。

戻り値

モチーフを表す DirectMusicSegment8 オブジェクトを返す。

エラー コード

失敗した場合はエラーが発生し、Err.Number が設定される。

参照

DirectMusicStyle8.GetMotifCount、DirectMusicStyle8.GetMotifName


DirectMusicStyle8.GetMotifCount

スタイル内で利用可能なモチーフ数を取得する。

object.GetMotifCount() As Long

指定項目

object
DirectMusicStyle8 オブジェクトを指定する。

戻り値

スタイル内で利用可能なモチーフ数を返す。

エラー コード

失敗した場合はエラーが発生し、Err.Number が設定される。


DirectMusicStyle8.GetMotifName

スタイル内のモチーフの名前を取得する。

object.GetMotifName(index As Long) As String

指定項目

object
DirectMusicStyle8 オブジェクトを指定する。
index
スタイル内のモチーフのインデックス。1 ～ DirectMusicStyle8.GetMotifCount が返す値の範囲で指定する。

戻り値

スタイルの作成者によってモチーフに割り当てられた名前を返す。

エラー コード

失敗した場合はエラーが発生し、Err.Number が設定される。

参照

DirectMusicStyle8.GetMotif


DirectMusicStyle8.GetTempo

スタイルの推奨テンポを取得する。

object.GetTempo() As Double

指定項目

object
DirectMusicStyle8 オブジェクトを指定する。

戻り値

1 分あたりの拍数で表された推奨テンポを返す。

エラー コード

失敗した場合はエラーが発生し、Err.Number が設定される。


DirectMusicStyle8.GetTimeSignature

スタイルの拍子記号を取得する。

object.GetTimeSignature(pTimeSig As DMUS_TIMESIGNATURE)

指定項目

object
DirectMusicStyle8 オブジェクトを指定する。
pTimeSig
拍子記号に関する情報を受け取る DMUS_TIMESIGNATURE 型。

エラー コード

失敗した場合はエラーが発生し、Err.Number が設定される。


DirectMusic 型

ここでは、DirectMusic for Visual Basic で使用される以下の型に関する情報を提供する。

  • DMUS_AUDIOPARAMS
  • DMUS_CURVE_PMSG
  • DMUS_NOTE_PMSG
  • DMUS_NOTIFICATION_PMSG
  • DMUS_TIMESIGNATURE


DMUS_AUDIOPARAMS

デフォルトのシンセサイザおよびパフォーマンスのバッファに必要なリソースを記述する。必要な機能を要求するため、およびどの要求が許可されたかに関する情報を受け取るために、DirectMusicPerformance8.InitAudio メソッドに渡される。

Type DMUS_AUDIOPARAMS
    clsidDefaultSynth As String
    fInitNow As Boolean
    lFeatures As Long
    lSampleRate As Long
    lValidData As Long
    lVoices As Long
End Type

メンバ

clsidDefaultSynth
デフォルトのシンセサイザのクラス識別子。これは、標準オーディオパスおよびデフォルトのシンセサイザを要求する構成から作成されたオーディオパスで使用されるシンセサイザである。この値がサポートされていない場合は、Microsoft のソフトウェア シンセサイザがデフォルトのシンセサイザである。
fInitNow
シンクとシンセサイザを即時に作成するかどうかを指定するブール値。 即時作成する場合は、この構造体に結果が返される。
lFeatures
パスの能力を指定するフラグ。0 または CONST_DMUS_AUDIO 列挙型の 1 つ以上の定数を指定できる。
lSampleRate
11,025 ～ 96,000 kHz の範囲のシンクおよびシンセサイザのサンプリング レート。デフォルト値は 22,050 である。
lValidData
この構造体のどのメンバが有効であるかを指定するフラグ。構造体が渡されたときに fInitNow が TRUE であれば、どのメンバがデータを受け取ったかを示すフラグを受け取る。「CONST_DMUS_AUDIOPARAMS」を参照すること。
lVoices
ボイス数。デフォルト値は 64 である。

参照

DirectMusicPerformance8.InitAudio


DMUS_CURVE_PMSG

カーブのメッセージに関する情報を保持する。

Type DMUS_CURVE_PMSG
    beat As Byte
    ccData As Byte
    curveShape As Byte
    endValue As Integer
    flags As Byte
    grid As Byte
    measure As Integer
    MergeIndex As Integer
    mtDuration As Long
    mtOriginalStart As Long
    mtResetDuration As Long
    offset As Integer
    ParamType As Integer
    resetValue As Integer
    startValue As Integer
    type As Byte
End Type

メンバ

beat
このカーブが発生する (小節内の) 拍数。
ccData
type が DMUS_CURVET_CCCURVE の場合は、コントローラ番号。
curveShape
カーブの形状。このパラメータには、CONST_DMUS_CURVES 列挙型のいずれかの値を指定できる。
endValue
カーブの終了値。
flags
フラグ。0 または CONST_DMUS_CURVE_FLAGS 列挙型の 1 つ以上の定数を指定できる。
grid
このカーブが発生する拍からのグリッド オフセット。アプリケーションで作成されたメッセージでは、0 でなければならない。
measure
カーブが発生する小節。アプリケーションで作成されたメッセージでは、0 でなければならない。
MergeIndex
マージ インデックス。ピッチ ベンド、ボリューム、およびエクスプレッション コントローラをサポートする。「注意」を参照すること。
mtDuration
カーブの持続時間。この値は、DirectMusicPerformance8.SendCurvePMSG の flags パラメータに DMUS_PMSGF_LOCKTOREFTIME が存在する場合を除き、ミュージック タイムで指定する。この場合の単位はミリ秒単位となり、テンポの変化によって影響を受けることはない。
mtOriginalStart
オリジナルの開始タイム。ミュージック タイムで指定する。アプリケーションで作成されたメッセージでは、0 でなければならない。
mtResetDuration
無効化に応答してリセットできる間のカーブの終わり後の時間の長さ。flags メンバに DMUS_CURVE_RESET がない場合は、無視される。この値は、DirectMusicPerformance8.SendCurvePMSG の flags パラメータに DMUS_PMSGF_LOCKTOREFTIME が存在する場合を除き、ミュージック タイムで指定する。この場合の単位はミリ秒単位となり、テンポの変化によって影響を受けることはない。
offset
カーブが発生するグリッドからのオフセット。ミュージック タイムで指定する。
ParamType
MIDI のパラメータ番号。「注意」を参照すること。
resetValue
フラッシュ (解放) または無効化後に設定する値。
startValue
カーブの開始値。
type
カーブのタイプ。このパラメータには、CONST_DMUS_CURVET 列挙型のいずれかの値を指定できる。

注意

ParamType の RPN または NRPN カーブ タイプは、7 ビットを付加した 2 バイトとして格納される。たとえば、MSB が 0x23、LSB が 0x74 である場合、ParamType の値は 0x2374 である。

startValue、endValue、および resetValue 内のデータは 14 ビットに制限される。7 ビットのバイト 2 つで構成される MIDI データの場合、値は空いている 2 ビットを付加して、1 ワードとして格納される。

MergeIndex に 0 が設定されたすべてのカーブは、相互にオーバーライドされる。マージ インデックスが別の値である場合、カーブが生成する値はマージ インデックス 0 の値に追加される。たとえば、アプリケーションが 0 と 3 のインデックスを持つカーブを使用する場合、0 カーブは常に相互に入れ替わるが 3 カーブに追加される。また、3 カーブも常に相互に入れ替わるが 0 カーブに追加される。

参照

DirectMusicPerformance8.SendCurvePMSG


DMUS_NOTE_PMSG

MIDI のノート イベントのデータを保持する。

Type DMUS_NOTE_PMSG
    beat as Byte
    durRange As Byte
    flags As Byte
    grid As Byte
    measure As Integer
    midiValue As Byte
    mtDuration As Long
    musicValue As Integer
    offset As Integer
    playModeFlags As Byte
    subChordLevel As Byte
    timeRange As Byte
    transpose As Integer
    velocity As Byte
    velRange As Byte
End Type

メンバ

beat
このノートが発生する (小節内の) 拍数。
durRange
ランダム持続時間の範囲。
flags
DMUS_NOTEF_NOTEON に設定しなければならない。「注意」を参照すること。
grid
このノートが発生する拍からのグリッド オフセット。
measure
ノートが発生する小節。
midiValue
MIDI ノートの値。
mtDuration
ノートの持続時間。ミュージック タイムで指定する。4 分音符あたり 768 ティックである。
musicValue
ノートの記述。ほとんどの演奏モードでは、以下に示すように、パックされた 4 ビット値の配列である。

-2 ～ 14 の範囲のオクターブ。このノートは、1 オクターブの 12 倍で上下に転置される。

0 ～ 15 の範囲のコード位置。ただし、3 を超えてはならない。コード内の最初の位置は 0 である。

0 ～ 15 の範囲のスケール位置。通常は 0 ～ 2 の範囲だが、1 ノートのコードにし、コードの上のすべてをスケール位置として解釈することも可能である。

－ 8 ～ 7 の範囲の変化音。通常は－ 2 ～ 2 の範囲。これは、スケールからノートを取り出すオフセットを表す。

固定演奏モードでは、ミュージック値は 0 ～ 127 の範囲にある MIDI ノートの値である。

offset
ノートが発生するグリッドからのオフセット。ミュージック タイムで指定する。
playModeFlags
ミュージック値がコードとサブコードにどのように関連するかを決定する演奏モード。値のリストについては、「CONST_DMUS_PLAYMODE_FLAGS」を参照すること。
subChordLevel
ノートが使用するサブコード レベル。
timeRange
ランダム時間の範囲。
transpose
musicValue からの変換後に midiValue に追加する転調。
velocity
ノートのベロシティ。
velRange
ベロシティをランダム化する範囲。

注意

ノート メッセージを送信するアプリケーションは、flags、midiValue、mtDuration、および velocity の各メンバだけに値を提供しなければならない。その他のメンバはツールだけによって利用される。ツールは DirectX for Visual Basic でサポートされていない。

アプリケーションは通常、flags を DMUS_NOTEF_NOTEON に設定する。アプリケーションはノートオフ メッセージを送信する必要はない。DirectMusic 出力ツールは、DMUS_NOTE_PMSG を受け取り、DMUS_NOTEF_NOTEON が設定されていることを認識すると、フラグを消去し、タイム スタンプに mtDuration を加え、メッセージを要求する。その結果、適切なタイムにノートは終了する。

ただし、アプリケーションは、flags が 0 に設定された同じチャンネル上の同じノートを送信することによって、ノートを途中で停止することができる。

参照

DirectMusicPerformance8.SendNotePMSG、ミュージック値と MIDI ノート


DMUS_NOTIFICATION_PMSG

パフォーマンスが送信する通知メッセージに関する情報を保持する。

Type DMUS_NOTIFICATION_PMSG
    ctTime As Long
    lField1 As Long
    lField2 As Long
    lNotificationOption As Long
    lNotificationType As Long
    mtTime As Long
    User As Unknown
End Type

メンバ

ctTime
メッセージのタイム スタンプ。クロック タイムで指定する。
lField1
通知タイプに固有の追加データ。DMUS_NOTIFY_ON_MEASUREANDBEAT 通知の場合、このメンバは小節内の拍番号を返す。
lField2
通知タイプに固有の追加データ。将来の使用またはアプリケーションによって定義される使用に備えて予約されている。
lNotificationOption
CONST_DMUS_NOTIFICATION_SUBTYPE 列挙型の通知サブタイプの識別子。

通知タイプが DMUS_NOTIFY_ON_SEGMENT の場合、このメンバは次の値のいずれかを保持する。

DMUS_NOTIFICATION_SEGABORT
セグメントが途中で停止した。またはプライマリ セグメントのキューから削除された。
DMUS_NOTIFICATION_SEGALMOSTEND
セグメントが終了タイムから準備時間を引いたタイムに達した。
DMUS_NOTIFICATION_SEGEND
セグメントが終了した。
DMUS_NOTIFICATION_SEGLOOP
セグメントがループした。
DMUS_NOTIFICATION_SEGSTART
セグメントが開始した。

通知タイプが DMUS_NOTIFY_ON_COMMAND の場合、このメンバは次の値のいずれかを保持する。

DMUS_NOTIFICATION_GROOVE
グルーブ チェンジ。
DMUS_NOTIFICATION_EMBELLISHMENT
装飾コマンド (イントロ、フィル、ブレーク、またはエンド)。

通知タイプが DMUS_NOTIFY_ON_PERFORMANCE の場合、このメンバは次の値のいずれかを保持する。

DMUS_NOTIFICATION_MUSICALMOSTEND
現在再生中のプライマリ セグメントが、終了タイムから準備時間を引いたタイムに達したが、キューにはもう再生するプライマリ セグメントはない。
DMUS_NOTIFICATION_MUSICSTARTED
再生が開始した。
DMUS_NOTIFICATION_MUSICSTOPPED
再生が停止した。

通知タイプが DMUS_NOTIFY_ON_MEASUREANDBEAT の場合、このメンバは DMUS_NOTIFICATION_MEASUREBEAT を保持する。その他のサブタイプは定義されない。

通知タイプが DMUS_NOTIFY_ON_CHORD の場合、このメンバは DMUS_NOTIFICATION_CHORD を保持する。その他のサブタイプは定義されない。

通知タイプが DMUS_NOTIFY_ON_RECOMPOSE の場合、このメンバは DMUS_NOTIFICATION_RECOMPOSE を保持する。その他のサブタイプは定義されない。

lNotificationType
CONST_DMUS_NOTIFICATION_TYPE 列挙型の通知タイプの識別子。
mtTime
メッセージのタイム スタンプ。ミュージック タイムで指定する。
User
イベントに関連付けられたオブジェクト。「注意」を参照すること。

注意

ほとんどの通知について、User メンバは DirectMusicSegmentState8 オブジェクトを保持する。アプリケーションがセグメント イベントの通知を受け取ると、DirectMusicSegmentState8.GetSegment を使用して、このオブジェクトから関連するセグメントを取得することができる。

GUID_NOTIFICATION_PERFORMANCE タイプの通知の場合、User メンバは常に Nothing である。

参照

DirectMusicPerformance8.AddNotificationType、DirectMusicPerformance8.GetNotificationPMSG


DMUS_TIMESIGNATURE

拍子記号に関する情報を保持する。この型は、DirectMusicPerformance8.GetTimeSig メソッドと DirectMusicStyle8.GetTimeSignature メソッドに渡され、DirectMusicPerformance8.SendTimeSigPMSG メソッドが送信するメッセージ内でも使用される。

Type DMUS_TIMESIGNATURE
    beat As Byte
    beatsPerMeasure As Byte
    gridsPerBeat As Integer
    mtTime As Long
End Type

メンバ

beat
拍子記号の分母。
beatsPerMeasure
拍子記号の分子。
gridsPerBeat
拍あたりのグリッド (小分割)。この値は、特定の音楽イベントのタイミング分解能を決定する。たとえば、DMUS_SEGF_GRID フラグを使ったセグメントの挿入が挙げられる。
mtTime
この拍子記号が発生するミュージック タイム。


DirectMusic 列挙型

DirectMusic for Visual Basic では、定数をグループ化する列挙型を使用して、Microsoft® Visual Studio® 開発環境のステートメント終了機能を活用する。

ここでは、以下の列挙型に関するリファレンス情報を提供する。

  • CONST_DMUS
  • CONST_DMUS_AUDIO
  • CONST_DMUS_AUDIOPARAMS
  • CONST_DMUS_COMMANDT_TYPES
  • CONST_DMUS_COMPOSEF_FLAGS
  • CONST_DMUS_CURVE_FLAGS
  • CONST_DMUS_CURVES
  • CONST_DMUS_CURVET
  • CONST_DMUS_NOTEF_FLAGS
  • CONST_DMUS_NOTIFICATION_SUBTYPE
  • CONST_DMUS_NOTIFICATION_TYPE
  • CONST_DMUS_PCHANNEL
  • CONST_DMUS_PLAYMODE_FLAGS
  • CONST_DMUS_PMSGF_FLAGS
  • CONST_DMUS_SEGF_FLAGS
  • CONST_DMUS_SHAPET_TYPES
  • CONST_DMUSERR
  • CONST_DMUSIC_PATH
  • CONST_DMUSIC_STANDARD_AUDIO_PATH


CONST_DMUS

DirectMusic で使用されるさまざまな定数を保持する。

Enum CONST_DMUS
    DMUS_MAXSUBCHORD =  8
    DMUS_TEMPO_MAX = 1000 (&H3E8)
    DMUS_TEMPO_MIN =    1
End Enum

定数

DMUS_MAXSUBCHORD
コード内で許可されるサブコードの最大数。
DMUS_TEMPO_MAX
最大テンポ。1 分あたりの拍数で表す。
DMUS_TEMPO_MIN
最小テンポ。1 分あたりの拍数で表す。


CONST_DMUS_AUDIOPARAMS

DMUS_AUDIOPARAMS 型の有効なメンバを指定するために使用される。

Enum CONST_DMUS_AUDIOPARAMS
    DMUS_AUDIOPARAMS_DEFAULTSYNTH =  8
    DMUS_AUDIOPARAMS_FEATURES     =  1
    DMUS_AUDIOPARAMS_SAMPLERATE   =  4
    DMUS_AUDIOPARAMS_VOICES       =  2
End Enum
DMUS_AUDIOPARAMS_DEFAULTSYNTH
clsidDefaultSynth メンバが有効なデータを保持する。
DMUS_AUDIOPARAMS_FEATURES
lFeatures メンバが有効なデータを保持する。
DMUS_AUDIOPARAMS_SAMPLERATE
lSampleRate メンバが有効なデータを保持する。
DMUS_AUDIOPARAMS_VOICES
lVoices メンバが有効なデータを保持する。


CONST_DMUS_AUDIO

オーディオパス内の機能を指定するために使用される。

Enum CONST_DMUS_AUDIO
    DMUS_AUDIOF_3D        =  1
    DMUS_AUDIOF_ALL       = 31 (&H1F)
    DMUS_AUDIOF_BUFFERS   = 32 (&h20)
    DMUS_AUDIOF_DMOS      =  8
    DMUS_AUDIOF_EAX       =  4
    DMUS_AUDIOF_ENVIRON   =  2
    DMUS_AUDIOF_STREAMING = 16 (&H10)
End Enum

定数

DMUS_AUDIOF_3D
3D バッファ。
DMUS_AUDIOF_ALL
ほかのすべてのフラグを組み合わせたもの。
DMUS_AUDIOF_BUFFERS
複数のバッファ。オーディオパスをフル サポートするには、このフラグを常に設定する必要がある。
DMUS_AUDIOF_DMOS
追加の DMO。
DMUS_AUDIOF_EAX
EAX エフェクト。
DMUS_AUDIOF_ENVIRON
環境モデリング。
DMUS_AUDIOF_STREAMING
ストリーミング ウェーブのサポート。


CONST_DMUS_COMMANDT_TYPES

ミュージック パターンを確立するコマンドを識別するために使用される。

Enum CONST_DMUS_COMMANDT_TYPES
    DMUS_COMMANDT_BREAK       = 3
    DMUS_COMMANDT_END         = 4
    DMUS_COMMANDT_ENDANDINTRO = 5
    DMUS_COMMANDT_FILL        = 1
    DMUS_COMMANDT_GROOVE      = 0
    DMUS_COMMANDT_INTRO       = 2
End Enum

定数

DMUS_COMMANDT_BREAK
ブレーク。
DMUS_COMMANDT_END
エンディング。
DMUS_COMMANDT_ENDANDINTRO
エンディングとイントロ。
DMUS_COMMANDT_FILL
フィル。
DMUS_COMMANDT_GROOVE
通常のグルーブ パターン。
DMUS_COMMANDT_INTRO
イントロ。

参照

DirectMusicComposer8.AutoTransition、DirectMusicComposer8.ComposeTransition、DirectMusicPerformance8.GetCommand


CONST_DMUS_COMPOSEF_FLAGS

トランジションのアレンジ内でフラグとして使用される。

Enum CONST_DMUS_COMPOSEF_FLAGS
    DMUS_COMPOSEF_1BAR_ADDITION       =  131072 (&H20000)
    DMUS_COMPOSEF_1BAR_TRANSITION     =   32768 (&H8000)
    DMUS_COMPOSEF_AFTERPREPARETIME    =      64 (&H40)
    DMUS_COMPOSEF_ALIGN               =       1
    DMUS_COMPOSEF_BEAT                =      16 (&H10)
    DMUS_COMPOSEF_DEFAULT             =  524288 (&H80000)
    DMUS_COMPOSEF_ENTIRE_ADDITION     =   65536 (&H10000)
    DMUS_COMPOSEF_ENTIRE_TRANSITION   =   16384 (&H4000)
    DMUS_COMPOSEF_GRID                =       8
    DMUS_COMPOSEF_IMMEDIATE           =       4
    DMUS_COMPOSEF_LONG                =    8192 (&H2000)
    DMUS_COMPOSEF_MARKER              =    2048 (&H800)
    DMUS_COMPOSEF_MEASURE             =      32 (&H20)
    DMUS_COMPOSEF_MODULATE            =    4096 (&H1000)
    DMUS_COMPOSEF_NOINVALIDATE        = 1048576 (&H100000)
    DMUS_COMPOSEF_NONE                =       0
    DMUS_COMPOSEF_OVERLAP             =       2
    DMUS_COMPOSEF_SEGMENTEND          =    1024 (&H400)
    DMUS_COMPOSEF_USE_AUDIOPATH       = 2097152 (&H200000)
    DMUS_COMPOSEF_VALID_START_BEAT    =     128 (&H80)
    DMUS_COMPOSEF_VALID_START_GRID    =     256 (&H100)
    DMUS_COMPOSEF_VALID_START_MEASURE =  262144 (&H40000)
    DMUS_COMPOSEF_VALID_START_TICK    =     512 (&H200)
End Enum

定数

DMUS_COMPOSEF_1BAR_ADDITION
追加のトランジション パターンの 1 小節を含める。DMUS_COMPOSEF_LONG が指定されている場合は、これがデフォルトの動作である。
DMUS_COMPOSEF_1BAR_TRANSITION
トランジション パターンの 1 小節を含める。
DMUS_COMPOSEF_AFTERPREPARETIME
AutoTransition のみ。トランジションを挿入するときは、DMUS_SEGF_AFTERPREPARETIME フラグ (「CONST_DMUS_SEGF_FLAGS」を参照) を使用する。
DMUS_COMPOSEF_ALIGN
トランジションを、現在演奏されているセグメントの拍子記号に揃える。
DMUS_COMPOSEF_BEAT
AutoTransition のみ。拍の境界からトランジションを開始する。
DMUS_COMPOSEF_DEFAULT
セグメントのデフォルトの境界を使用する。
DMUS_COMPOSEF_ENTIRE_ADDITION
追加のトランジション パターンを完全な形で含める。DMUS_COMPOSEF_LONG と組み合わせて使用される。
DMUS_COMPOSEF_ENTIRE_TRANSITION
トランジション パターン全体を含める。
DMUS_COMPOSEF_GRID
AutoTransition のみ。グリッド境界からトランジションを開始する。
DMUS_COMPOSEF_IMMEDIATE
AutoTransition のみ。ミュージック タイムまたはクロック タイムの境界からトランジションを開始する。
DMUS_COMPOSEF_LONG
長いトランジションをアレンジする。このフラグが設定されていない場合、ComposeTransition または AutoTransition の lCommand パラメータでエンディングを指定し、スタイルに 1 小節より長いエンディングが含まれていない限り、トランジションの長さは最大でも 1 小節である。このフラグが設定されている場合、トランジションの長さは 1 小節増える。
DMUS_COMPOSEF_MARKER
現在のセグメントの次のマーカーでトランジションを演奏する。
DMUS_COMPOSEF_MEASURE
AutoTransition のみ。小節境界からトランジションを開始する。
DMUS_COMPOSEF_MODULATE
toSeg のコードを使用して、fromSeg から toSeg へスムーズに変化するトランジションをアレンジする。
DMUS_COMPOSEF_NOINVALIDATE
演奏中のセグメントを無効化しない。
DMUS_COMPOSEF_NONE
フラグなし。デフォルトでは、トランジションは小節境界から開始する。
DMUS_COMPOSEF_OVERLAP
トランジションを toSeg に重ねる (オーバーラップ)。現在実装されていない。
DMUS_COMPOSEF_SEGMENTEND
現在のセグメントの最後にトランジションを演奏する。
DMUS_COMPOSEF_USE_AUDIOPATH
セグメントに埋め込まれたオーディオパスを使用する。
DMUS_COMPOSEF_VALID_START_BEAT
任意の拍で切り替えを発生できる。DMUS_COMPOSEF_ALIGN と組み合わせて使用される。
DMUS_COMPOSEF_VALID_START_GRID
任意のグリッドで切り替えを発生できる。DMUS_COMPOSEF_ALIGN と組み合わせて使用される。
DMUS_COMPOSEF_VALID_START_MEASURE
任意の小節で切り替えを発生できる。DMUS_COMPOSEF_ALIGN と組み合わせて使用される。
DMUS_COMPOSEF_VALID_START_TICK
任意のタイムで切り替えを発生できる。DMUS_COMPOSEF_ALIGN と組み合わせて使用される。

参照

DirectMusicComposer8.AutoTransition、DirectMusicComposer8.ComposeTransition


CONST_DMUS_CURVE_FLAGS

DMUS_CURVE_PMSG 型の flags メンバで使用される。

Enum CONST_DMUS_CURVE_FLAGS
    DMUS_CURVE_RESET              = 1
    DMUS_CURVE_START_FROM_CURRENT = 2
End Enum

定数

DMUS_CURVE_RESET
デフォルトのタイムに達したとき、またはトランジションが原因で無効化が発生したときに resetValue メンバの値を設定しなければならない。このフラグが設定されていない場合、カーブは新しい値に永続的にとどまる。
DMUS_CURVE_START_FROM_CURRENT
nStartValue を無視し、現在の値でカーブを開始する。ボリューム、エクスプレッション、ピッチ ベンド、フィルタ カットオフ、パン、およびモッド ホイール用に実装される。


CONST_DMUS_CURVES

DMUS_CURVE_PMSG 型でカーブの形状を定義するために使用される。

Enum CONST_DMUS_CURVES
    DMUS_CURVES_EXP       = 2
    DMUS_CURVES_INSTANT   = 1
    DMUS_CURVES_LINEAR    = 0
    DMUS_CURVES_LOG       = 3
    DMUS_CURVES_SINE      = 4
End Enum

定数

DMUS_CURVES_EXP
指数カーブ形状。
DMUS_CURVES_INSTANT
即時カーブ形状 (カーブの開始と終了がほとんど同時に発生する)。
DMUS_CURVES_LINEAR
線状カーブ形状。
DMUS_CURVES_LOG
対数カーブ形状。
DMUS_CURVES_SINE
正弦カーブ形状。


CONST_DMUS_CURVET

DMUS_CURVE_PMSG 型で MIDI コントローラを記述するために使用される。

Enum CONST_DMUS_CURVET
    DMUS_CURVET_CCCURVE   = 4
    DMUS_CURVET_MATCURVE  = 5
    DMUS_CURVET_NRPNCURVE = 8
    DMUS_CURVET_PATCURVE  = 6
    DMUS_CURVET_PBCURVE   = 3
    DMUS_CURVET_RPNCURVE  = 7
End Enum

定数

DMUS_CURVET_CCCURVE
コンティニュアス コントローラ カーブ (MIDI Control Change チャンネル ボイス メッセージ。ステータス バイトは &HBn。n はチャンネル番号を表す)。
DMUS_CURVET_MATCURVE
モノラル アフタータッチ カーブ (MIDI Channel Pressure チャンネル ボイス メッセージ。ステータス バイトは &HDn)。
DMUS_CURVET_NRPNCURVE
ParamType メンバに定義されたタイプの NRPN カーブ。
DMUS_CURVET_PATCURVE
ポリフォニック アフタータッチ カーブ (MIDI Poly Key Pressure チャンネル ボイス メッセージ。ステータス バイトは &HDn)。
DMUS_CURVET_PBCURVE
ピッチベンド カーブ (MIDI Pitch Bend チャンネル ボイス メッセージ。ステータス バイトは &HEn)。
DMUS_CURVET_RPNCURVE
ParamType に定義されたタイプの RPN カーブ。


CONST_DMUS_NOTEF_FLAGS

ノート メッセージで使用される。

Enum CONST_DMUS_NOTEF_FLAGS
    DMUS_NOTEF_NOTEON = 1
End Enum

定数

DMUS_NOTEF_NOTEON
「DMUS_NOTE_PMSG」の「注意」を参照すること。


CONST_DMUS_NOTIFICATION_SUBTYPE

通知メッセージ内で報告される音楽イベントに関する情報を提供する。

Enum CONST_DMUS_NOTIFICATION_SUBTYPE
    DMUS_NOTIFICATION_CHORD          = 0
    DMUS_NOTIFICATION_EMBELLISHMENT  = 1
    DMUS_NOTIFICATION_GROOVE         = 0
    DMUS_NOTIFICATION_MEASUREBEAT    = 0
    DMUS_NOTIFICATION_MUSICALMOSTEND = 2
    DMUS_NOTIFICATION_MUSICSTARTED   = 0
    DMUS_NOTIFICATION_MUSICSTOPPED   = 1
    DMUS_NOTIFICATION_RECOMPOSE      = 0
    DMUS_NOTIFICATION_SEGABORT       = 4
    DMUS_NOTIFICATION_SEGALMOSTEND   = 2
    DMUS_NOTIFICATION_SEGEND         = 1
    DMUS_NOTIFICATION_SEGLOOP        = 3
    DMUS_NOTIFICATION_SEGSTART       = 0
End Enum

定数の説明については、「DMUS_NOTIFICATION_PMSG」を参照すること。


CONST_DMUS_NOTIFICATION_TYPE

通知タイプを識別するために使用される。これらの定数は、DirectMusicPerformance8.AddNotificationType メソッドと DirectMusicPerformance8.RemoveNotificationType メソッドに渡され、DirectMusicPerformance8.GetNotificationPMSG が取得するメッセージ内の通知タイプを識別する。

Enum CONST_DMUS_NOTIFICATION_TYPE
    DMUS_NOTIFY_ON_CHORD          = 1
    DMUS_NOTIFY_ON_COMMAND        = 2
    DMUS_NOTIFY_ON_MEASUREANDBEAT = 3
    DMUS_NOTIFY_ON_PERFORMANCE    = 4
    DMUS_NOTIFY_ON_RECOMPOSE =      0
    DMUS_NOTIFY_ON_SEGMENT        = 5
End Enum

定数

DMUS_NOTIFY_ON_CHORD
コード チェンジ。
DMUS_NOTIFY_ON_COMMAND
コマンド イベント。
DMUS_NOTIFY_ON_MEASUREANDBEAT
小節および拍イベント。
DMUS_NOTIFY_ON_PERFORMANCE
パフォーマンス イベント。この値が DMUS_NOTIFICATION_PMSG 型の lNotificationType メンバ内で見つかった場合、イベントは lNotificationOption メンバ内でさらに定義される。
DMUS_NOTIFY_ON_RECOMPOSE
再アレンジ イベント。この値が DMUS_NOTIFICATION_PMSG 型の lNotificationType メンバ内で見つかった場合、イベントは lNotificationOption メンバ内でさらに定義される。
DMUS_NOTIFY_ON_SEGMENT
セグメント イベント。この値が DMUS_NOTIFICATION_PMSG 型の lNotificationType メンバ内で見つかった場合、イベントは lNotificationOption メンバ内でさらに定義される。

参照

DMUS_NOTIFICATION_PMSG


CONST_DMUS_PCHANNEL

複数のパフォーマンス チャンネルにメッセージを送るために使用される。オーディオパス内のオブジェクトに対する複数のチャンネルを検索するには、DMUS_PCHANNEL_ALL を使用する。

Enum CONST_DMUS_PCHANNEL
    DMUS_PCHANNEL_ALL                   = -5 (&HFFFFFFFB)
    DMUS_PCHANNEL_BROADCAST_AUDIOPATH   = -2 (&HFFFFFFFE)
    DMUS_PCHANNEL_BROADCAST_GROUPS      = -4 (&HFFFFFFFC)
    DMUS_PCHANNEL_BROADCAST_PERFORMANCE = -1 (&HFFFFFFFF)
    DMUS_PCHANNEL_BROADCAST_SEGMENT     = -3 (&HFFFFFFFD)
End Enum

定数

DMUS_PCHANNEL_ALL
すべてのチャンネルを検索する。
DMUS_PCHANNEL_BROADCAST_AUDIOPATH
オーディオパスのすべてのチャンネルにメッセージのコピーを送信する。
DMUS_PCHANNEL_BROADCAST_GROUPS
パフォーマンス内の各チャンネル グループにメッセージのコピーを送信する。システム エクスクルーシブ メッセージなど、メッセージを各チャンネル グループに一度だけ送信する必要がある場合に使用する。
DMUS_PCHANNEL_BROADCAST_PERFORMANCE
パフォーマンスのすべてのチャンネルにメッセージのコピーを送信する。
DMUS_PCHANNEL_BROADCAST_SEGMENT
セグメントのすべてのチャンネルにメッセージのコピーを送信する。


CONST_DMUS_PLAYMODE_FLAGS

DMUS_NOTE_PMSG メッセージ タイプに演奏モードを設定するために使用される。演奏モードによって、ノートが MIDI ノートに変換される前に、現在のコードに転置される方法が決まる。

Enum CONST_DMUS_PLAYMODE_FLAGS
    DMUS_PLAYMODE_ALWAYSPLAY     = 14
    DMUS_PLAYMODE_CHORD_INTERVALS = 8
    DMUS_PLAYMODE_CHORD_ROOT      = 2
    DMUS_PLAYMODE_FIXED           = 0
    DMUS_PLAYMODE_FIXEDTOCHORD    = 2
    DMUS_PLAYMODE_FIXEDTOKEY      = 1
    DMUS_PLAYMODE_KEY_ROOT        = 1
    DMUS_PLAYMODE_MELODIC         = 6
    DMUS_PLAYMODE_NONE           = 16 (&H10)
    DMUS_PLAYMODE_NORMALCHORD    = 10
    DMUS_PLAYMODE_PEDALPOINT      = 5
    DMUS_PLAYMODE_SCALE_INTERVALS = 4
End Enum

定数

The following members are the basic flags:
DMUS_PLAYMODE_CHORD_INTERVALS
コード パターンのコードの音程を使用する。
DMUS_PLAYMODE_CHORD_ROOT
コードのルート音上に転置する。
DMUS_PLAYMODE_KEY_ROOT
キーのルート音上に転置する。
DMUS_PLAYMODE_NONE
モードなし。親パートのモードを使用する必要があることを示す。
DMUS_PLAYMODE_SCALE_INTERVALS
スケール パターンのスケールの音程を使用する。
The following members represent combinations of the basic flags:
DMUS_PLAYMODE_ALWAYSPLAY
DMUS_PLAYMODE_SCALE_INTERVALS、DMUS_PLAYMODE_CHORD_INTERVALS、および DMUS_PLAYMODE_CHORD_ROOT の組み合わせ。コードの最高音より高いノートを演奏することが望ましい場合、このモードは、スケールの音程を使用することによってノートの位置を検索する。つまり、このモードは通常の演奏モードと旋律系の演奏モードの組み合わせであり、通常モードで失敗すると 2 回目の試行が旋律系モードで強制的に行われる。
DMUS_PLAYMODE_FIXED
ミュージック値を MIDI 値として解釈する。これは 0 として定義され、その他のフラグがないことを意味する。このフラグは、ドラム、サウンド エフェクト、およびコードまたはスケールによって転置してはならない、シーケンス化されたノートについて使用される。
DMUS_PLAYMODE_FIXEDTOCHORD
DMUS_PLAYMODE_CHORD_ROOT と同じ。ミュージック値は固定の MIDI 値であるが、コードのルート音上に転置される。
DMUS_PLAYMODE_FIXEDTOKEY
DMUS_PLAYMODE_KEY_ROOT と同じ。ミュージック値は固定の MIDI 値であるが、キーのルート音上に転置される。
DMUS_PLAYMODE_MELODIC
DMUS_PLAYMODE_CHORD_ROOT と DMUS_PLAYMODE_SCALE_INTERVALS の組み合わせ。コードのルート音は使用されるが、ノートはスケール内の音程だけを追う。キーのルート音とコードの音程は無視される。これは、コードのルート音を基準にして演奏される旋律系のラインにとって便利である。
DMUS_PLAYMODE_NORMALCHORD
DMUS_PLAYMODE_CHORD_ROOT と DMUS_PLAYMODE_CHORD_INTERVALS の組み合わせ。これは一般的な再生モードである。ノートはコード内の音程を追う。コードはコードのルート音に基づいている。ミュージック値にスケール要素がある場合、ほかの音程は音階から取り出され、追加される。コードがミュージック値のコード要素と一致する音程を持っていない場合、ノートは無音である。
DMUS_PLAYMODE_PEDALPOINT
DMUS_PLAYMODE_KEY_ROOT と DMUS_PLAYMODE_SCALE_INTERVALS の組み合わせ。キーのルート音が使用され、ノートはスケール内の音程だけを追う。コードのルート音と音程は無視される。これは、キーのルート音を基準にして演奏される旋律系のラインにとって便利である。


CONST_DMUS_PMSGF_FLAGS

CONST_DMUS_PMSGF_FLAGS 列挙のメンバは、DirectMusicPerformance8 のさまざまなメッセージ送信メソッドで使用される。

Enum CONST_DMUS_PMSGF_FLAGS
    DMUS_PMSGF_DX8            = 128 (&H80)
    DMUS_PMSGF_LOCKTOREFTIME  =  64 (&H40)
    DMUS_PMSGF_MUSICTIME      =   2
    DMUS_PMSGF_REFTIME        =   1
    DMUS_PMSGF_TOOL_ATTIME    =  16 (&H10)
    DMUS_PMSGF_TOOL_FLUSH     =  32 (&H20)
    DMUS_PMSGF_TOOL_IMMEDIATE =   4
    DMUS_PMSGF_TOOL_QUEUE     =   8
End Enum

定数

DMUS_PMSGF_DX8
メッセージは、DirectX 8.0 より前のバージョンに存在しない、有効なメンバを持っている。このフラグを DirectX for Visual Basic で設定する必要はない。
DMUS_PMSGF_LOCKTOREFTIME
メッセージのクロック タイムは、テンポの変更によって変えることはできない。
DMUS_PMSGF_REFTIME
タイム スタンプはクロック タイムで表される。
DMUS_PMSGF_MUSICTIME
タイプ スタンプはミュージック タイムで表される。
DMUS_PMSGF_TOOL_IMMEDIATE
DMUS_PMSGF_TOOL_QUEUE
DMUS_PMSGF_TOOL_ATTIME
DMUS_PMSGF_TOOL_FLUSH
「注意」を参照すること。

注意

DirectX for Visual Basic は DirectMusic ツールをサポートしないため、DMUS_PMSGF_REFTIME と DMUS_PMSGF_MUSICTIME だけが現在有効である。メッセージのタイムはデフォルトでミュージック タイムで表されるため、DMUS_PMSGF_REFTIME はアプリケーションが通常使用する唯一のフラグである。


CONST_DMUS_SEGF_FLAGS

CONST_DMUS_SEGF_FLAGS 列挙型のメンバは、セグメントに対するアクションのタイミングやその他の要素を制御するために、DirectMusicPerformance8 オブジェクトのさまざまなメソッド内で使用される。

Enum CONST_DMUS_SEGF_FLAGS
    DMUS_SEGF_AFTERLATENCYTIME    =   4194304 (&H400000)
    DMUS_SEGF_AFTERPREPARETIME    =      1024 (&H400)
    DMUS_SEGF_AFTERQUEUETIME      =   2097152 (&H200000)
    DMUS_SEGF_ALIGN               =     65536 (&H10000)
    DMUS_SEGF_AUTOTRANSITION      =   1048576 (&H100000)
    DMUS_SEGF_BEAT                =      4096 (&H1000)
    DMUS_SEGF_CONTROL             =       512 (&H200)
    DMUS_SEGF_DEFAULT             =     16384 (&H4000)
    DMUS_SEGF_GRID                =      2048 (&H800)
    DMUS_SEGF_MARKER              =  16777216 (&H1000000)
    DMUS_SEGF_MEASURE             =      8192 (&H2000)
    DMUS_SEGF_NOINVALIDATE        =     32768 (&H8000)
    DMUS_SEGF_QUEUE               =       256 (&H100)
    DMUS_SEGF_REFTIME             =        64 (&H40)
    DMUS_SEGF_SECONDARY           =       128 (&H80)
    DMUS_SEGF_SEGMENTEND          =   8388608 (&H800000)
    DMUS_SEGF_TIMESIG_ALWAYS      =  33554432 (&H2000000)
    DMUS_SEGF_USE_AUDIOPATH       =  67108864 (&H4000000)
    DMUS_SEGF_VALID_START_BEAT    =    131072 (&H20000)
    DMUS_SEGF_VALID_START_GRID    =    262144 (&H40000)
    DMUS_SEGF_VALID_START_MEASURE = 134217728 (&H8000000
    DMUS_SEGF_VALID_START_TICK    =    524288 (&H80000)
End Enum

定数

DMUS_SEGF_AFTERLATENCYTIME
遅延時間の後に演奏する。これはすべてのセグメントに当てはまるので、このフラグは現時点では何の効果もない。
DMUS_SEGF_AFTERPREPARETIME
準備時間の後に演奏する。
DMUS_SEGF_AFTERQUEUETIME
キュー時間の後に演奏する。これはプライマリ セグメントのデフォルトである。DMUS_SEGF_AFTERPREPARETIME も設定されている場合は無視される。
DMUS_SEGF_ALIGN
セグメントの開始を、小節や拍など、既に過ぎた境界に揃えることができる。これを実行するには、セグメント内で次の境界の前に、有効な開始ポイントがある必要がある。開始ポイントはセグメント内に定義できる。また、DMUS_SEGF_VALID_START_xxx フラグの 1 つを使用して、有効な開始ポイントの細分度を定義できる。DMUS_SEGF_VALID_START_xxx フラグは、セグメント内に有効な開始ポイントが定義されていない場合にのみ有効である。
DMUS_SEGF_AUTOTRANSITION
トランジション テンプレートを使用して、トランジション セグメントをアレンジおよび演奏する。
DMUS_SEGF_BEAT
拍の境界で演奏する。
DMUS_SEGF_CONTROL
制御セグメントとして演奏する (セカンダリ セグメントのみ)。「注意」を参照すること。
DMUS_SEGF_DEFAULT
セグメントのデフォルトの境界を使用する。
DMUS_SEGF_GRID
グリッド境界で演奏する。
DMUS_SEGF_MARKER
プライマリ セグメント内の次のマーカーで演奏する。マーカーが存在しない場合は、その他の解決フラグを使用する。
DMUS_SEGF_MEASURE
小節境界で演奏する。
DMUS_SEGF_NOINVALIDATE
プライマリ セグメントまたは制御セグメントについて、このフラグを DirectMusicPerformance8.PlaySegmentEx 内で設定すると、新しいセグメントで無効化が発生しない。このフラグがないと無効化が発生し、演奏中のカーブやノートが途切れ、リセットされる。このフラグは DMUS_SEGF_AFTERPREPARETIME と組み合わせなければならない。そうすることによって、新しいセグメント内のノートは、古いセグメントが演奏するノートに重ねて演奏しない。
DMUS_SEGF_QUEUE
プライマリ セグメント キューの最後に置く (プライマリ セグメントのみ)。
DMUS_SEGF_REFTIME
タイム パラメータはクロック タイムで表される。
DMUS_SEGF_SECONDARY
セカンダリ セグメント。
DMUS_SEGF_SEGMENTEND
開始タイムで演奏中のプライマリ セグメントの最後で演奏する。現在演奏中のプライマリ セグメント後に既に挿入されているセグメントは、フラッシュ (解放) される。プライマリ セグメントが演奏されていない場合は、その他の解決フラグを使用する。
DMUS_SEGF_TIMESIG_ALWAYS
開始タイムを現在の拍子記号に揃える。プライマリ セグメントがない場合も同様にする。
DMUS_SEGF_USE_AUDIOPATH
セグメントに埋め込まれたオーディオパスを使用する。サウンドが正しく演奏されるように、バンドの自動ダウンロードを有効にする必要がある。
DMUS_SEGF_VALID_START_BEAT
任意の拍で開始できる。DMUS_SEGF_ALIGN と組み合わせて使用される。
DMUS_SEGF_VALID_START_GRID
任意のグリッドで開始できる。DMUS_SEGF_ALIGN と組み合わせて使用される。
DMUS_SEGF_VALID_START_MEASURE
任意の小節で開始できる。DMUS_SEGF_ALIGN と組み合わせて使用される。
DMUS_SEGF_VALID_START_TICK
任意のタイムで開始できる。DMUS_SEGF_ALIGN と組み合わせて使用される。

注意

通常、プライマリ セグメントは制御セグメントである。DMUS_SEGF_CONTROL フラグを使用して、セカンダリ セグメントを制御セグメントにすることができる。ただし、制御セグメントが存在できるのは一度に 1 つだけである (複数の制御セグメントを作成することはできるが、実際にどの制御セグメントが DirectMusic によって使用されるかは保証されない)。デフォルトでは、制御セグメントだけがテンポ メッセージを送信する。

DMUS_SEGF_CONTROL フラグを設定すると、DMUS_SEGF_SECONDARY が想定される。

次の各グループの中から 2 つ以上のフラグを指定してはいけない。

境界
このフラグは、キューにあるセグメントの開始ポイントが位置する現在演奏中のプライマリ セグメントのポイントを制御する。DMUS_SEGF_MARKER と組み合わせることができる。この場合、境界フラグはプライマリ セグメント内にマーカーが存在しない場合にのみ使用される。

DMUS_SEGF_BEAT
DMUS_SEGF_DEFAULT
DMUS_SEGF_GRID
DMUS_SEGF_MEASURE
DMUS_SEGF_QUEUE
DMUS_SEGF_SEGMENTEND

整列
このフラグは、キューにあるセグメントのセグメント開始タイムを制御する。この時点で、演奏時間は過去のものとなる。DMUS_SEGF_ALIGN と組み合わせる必要がある。

DMUS_SEGF_VALID_START_BEAT
DMUS_SEGF_VALID_START_GRID
DMUS_SEGF_VALID_START_MEASURE
DMUS_SEGF_VALID_START_TICK

各グループのフラグを 1 つずつ組み合わせることは可能である。たとえば、DMUS_SEGF_MEASURE に DMUS_SEGF_ALIGN と DMUS_SEGF_VALID_START_BEAT を組み合わせると、キューにあるセグメントの開始ポイントが現在のプライマリ セグメントの小節境界に置かれる。この境界を既に過ぎている場合、キューに置かれているセグメントは、過ぎた時間に揃えられていないセグメント内の次の拍の境界から演奏を開始する。詳細については、「セグメントのタイミング」を参照すること。

参照

DirectMusicPerformance8.GetResolvedTime、DirectMusicPerformance8.Invalidate、DirectMusicPerformance8.PlaySegmentEx、DirectMusicPerformance8.StopEx


CONST_DMUS_SHAPET_TYPES

CONST_DMUS_SHAPET_TYPES 列挙型のメンバは、DirectMusicComposer8.ComposeSegmentFromShape メソッドと DirectMusicComposer8.ComposeTemplateFromShape メソッドの wShape パラメータ内で使用され、グルーブ レベルの希望のパターンを指定する。

Enum CONST_DMUS_SHAPET_TYPES
    DMUS_SHAPET_FALLING  = 0
    DMUS_SHAPET_LEVEL    = 1
    DMUS_SHAPET_LOOPABLE = 2
    DMUS_SHAPET_LOUD     = 3
    DMUS_SHAPET_PEAKING  = 5
    DMUS_SHAPET_QUIET    = 4
    DMUS_SHAPET_RANDOM   = 6
    DMUS_SHAPET_RISING   = 7
    DMUS_SHAPET_SONG     = 8
End Enum

定数

DMUS_SHAPET_FALLING
グルーブ レベルは下降する。
DMUS_SHAPET_LEVEL
グルーブ レベルは均等に保たれる。
DMUS_SHAPET_LOOPABLE
セグメントは先頭にループするよう調整されている。
DMUS_SHAPET_LOUD
グルーブ レベルは高い。
DMUS_SHAPET_PEAKING
グルーブ レベルはピークまで上昇し、その後下降する。
DMUS_SHAPET_QUIET
グルーブ レベルは低い。
DMUS_SHAPET_RANDOM
グルーブ レベルはランダムである。
DMUS_SHAPET_RISING
グルーブ レベルは上昇する。
DMUS_SHAPET_SONG
セグメントはソングの形式である。6 ～ 8 小節から成る複数の楽句をアレンジし、まとめることによって、グルーブ レベルにバリエーションのあるヴァースコーラス エフェクトが生み出される。


CONST_DMUSERR

CONST_DMUSERR 列挙型は、DirectMusic のエラー コードを表す。値のリストについては、「DirectMusic エラー コード」を参照すること。


CONST_DMUSIC_PATH

オブジェクトを取得するオーディオパスのステージを指定するために使用される。これらのフラグの一部は、DirectMusicAudioPath8.GetObjectInPath メソッドを使用するときに有効である。

取得できるオブジェクトの中には、DirectX for Visual Basic でサポートされていないものもある。詳細については、「オーディオパスからのオブジェクトの取得」を参照すること。

Enum CONST_DMUSIC_PATH
    DMUS_PATH_AUDIOPATH          =  8192 (&H2000)
    DMUS_PATH_AUDIOPATH_GRAPH    =  8704 (&H2200)
    DMUS_PATH_AUDIOPATH_TOOL     =  8960 (&H2300)
    DMUS_PATH_BUFFER             = 24576 (&H6000)
    DMUS_PATH_BUFFER_DMO         = 24832 (&H6100)
    DMUS_PATH_MIXIN_BUFFER       = 28672 (&H7000)
    DMUS_PATH_MIXIN_BUFFER_DMO   = 28928 (&H7100)
    DMUS_PATH_PERFORMANCE        = 12288 (&H3000)
    DMUS_PATH_PERFORMANCE_GRAPH  = 12800 (&H3200)
    DMUS_PATH_PERFORMANCE_TOOL   = 13056 (&H3300)
    DMUS_PATH_PORT               = 16384 (&H4000)
    DMUS_PATH_PRIMARY_BUFFER     = 32768 (&H8000)
    DMUS_PATH_SEGMENT            =  4096 (&H1000)
    DMUS_PATH_SEGMENT_GRAPH      =  4608 (&H1200)
    DMUS_PATH_SEGMENT_TOOL       =  4864 (&H1300)
    DMUS_PATH_SEGMENT_TRACK      =  4352 (&H1100)
End Enum

定数

DMUS_PATH_AUDIOPATH
セグメント状態からオーディオパスを取得する。
DMUS_PATH_AUDIOPATH_GRAPH
オーディオパス ツール グラフを取得する。存在しなければ作成される。
DMUS_PATH_AUDIOPATH_TOOL
オーディオパス ツール グラフからツールを取得する。
DMUS_PATH_BUFFER
DirectSound バッファを取得する。
DMUS_PATH_BUFFER_DMO
バッファ内の DMO を取得する。
DMUS_PATH_MIXIN_BUFFER
グローバル ミックスイン バッファを取得する。
DMUS_PATH_MIXIN_BUFFER_DMO
グローバル ミックスイン バッファ内の DMO を取得する。
DMUS_PATH_PERFORMANCE
パフォーマンスを取得する。
DMUS_PATH_PERFORMANCE_GRAPH
パフォーマンス ツール グラフを取得する。存在しなければ作成される。
DMUS_PATH_PERFORMANCE_TOOL
パフォーマンス グラフ内のツールを取得する。
DMUS_PATH_PORT
シンセサイザを取得する。
DMUS_PATH_PRIMARY_BUFFER
プライマリ バッファを取得する。
DMUS_PATH_SEGMENT
このセグメント状態を所有するセグメントを取得する。
DMUS_PATH_SEGMENT_GRAPH
セグメント ツール グラフを取得する。存在しなければ作成される。
DMUS_PATH_SEGMENT_TOOL
セグメント グラフからツールを取得する。「注意」を参照すること。
DMUS_PATH_SEGMENT_TRACK
セグメントからトラックを取得する。


CONST_DMUSIC_STANDARD_AUDIO_PATH

DirectMusicPerformance8.CreateStandardAudioPath または DirectMusicPerformance8.InitAudio を使用して、作成するオーディオパスを指定するために使用される。

Enum CONST_DMUSIC_STANDARD_AUDIO_PATH
    DMUS_APATH_DYNAMIC_3D              = 6
    DMUS_APATH_DYNAMIC_MONO            = 7
    DMUS_APATH_DYNAMIC_STEREO          = 8
    DMUS_APATH_SHARED_STEREOPLUSREVERB = 1
End Enum

定数

DMUS_APATH_DYNAMIC_3D
シンセサイザの出力から 3D バッファへのバスを 1 つ備えたオーディオパス。
DMUS_APATH_DYNAMIC_MONO
モノラル バッファを 1 つ備えたオーディオ環境。
DMUS_APATH_DYNAMIC_STEREO
ステレオ バッファを 1 つ備えたオーディオ環境。
DMUS_APATH_SHARED_STEREOPLUSREVERB
ステレオ バッファと環境リバーブを備えたバッファがそれぞれ 1 つ装備されているオーディオ環境。


DirectMusic エラー コード

ここでは、DirectMusic のメソッドによって返される可能性のあるさまざまなエラー コードについて簡単に説明する。各メソッドが返す特定のエラー コードのリストについては、個別のメソッドの説明を参照すること。これらのリストは必ずしも包括的なものとは限らない。

エラー コードは以下のトピックに示されている。

  • DirectMusic エラー コード (値)
  • DirectMusic エラー コード (名前)


DirectMusic エラー コード (値)

次の表は、値で格納される DirectMusic エラー コードを示している。説明については、定数をクリックすること。

16 進数 | 定数
&H00001AE | DMUS_E_NOINTERFACE
&H00001BD | DMUS_E_NOTIMPL
&H80070057 | DMUS_E_FAIL
&H88781101 | DMUS_E_DRIVER_FAILED
&H88781102 | DMUS_E_PORTS_OPEN
&H88781103 | DMUS_E_DEVICE_IN_USE
&H88781104 | DMUS_E_INSUFFICIENTBUFFER
&H88781105 | DMUS_E_BUFFERNOTSET
&H88781106 | DMUS_E_BUFFERNOTAVAILABLE
&H88781108 | DMUS_E_NOTADLSCOL
&H88781109 | DMUS_E_INVALIDOFFSET
&H88781111 | DMUS_E_ALREADY_LOADED
&H88781113 | DMUS_E_INVALIDPOS
&H88781114 | DMUS_E_INVALIDPATCH
&H88781115 | DMUS_E_CANNOTSEEK
&H88781116 | DMUS_E_CANNOTWRITE
&H88781117 | DMUS_E_CHUNKNOTFOUND
&H88781119 | DMUS_E_INVALID_DOWNLOADID
&H88781120 | DMUS_E_NOT_DOWNLOADED_TO_PORT
&H88781121 | DMUS_E_ALREADY_DOWNLOADED
&H88781122 | DMUS_E_UNKNOWNDOWNLOAD
&H88781123 | DMUS_E_SET_UNSUPPORTED
&H88781124 | DMUS_E_GET_UNSUPPORTED
&H88781125 | DMUS_E_NOTMONO
&H88781126 | DMUS_E_BADARTICULATION
&H88781127 | DMUS_E_BADINSTRUMENT
&H88781128 | DMUS_E_BADWAVELINK
&H88781128 | DMUS_E_BUFFER_EMPTY
&H8878112A | DMUS_E_NOTPCM
&H8878112B | DMUS_E_BADWAVE
&H8878112C | DMUS_E_BADOFFSETTABLE
&H8878112D | DMUS_E_UNKNOWN_PROPERTY
&H8878112E | DMUS_E_NOSYNTHSINK
&H8878112F | DMUS_E_ALREADYOPEN
&H88781130 | DMUS_E_ALREADYCLOSED
&H88781131 | DMUS_E_SYNTHNOTCONFIGURED
&H88781132 | DMUS_E_SYNTHACTIVE
&H88781133 | DMUS_E_CANNOTREAD
&H88781134 | DMUS_E_DMUSIC_RELEASED
&H88781136 | DMUS_E_BUFFER_FULL
&H88781137 | DMUS_E_PORT_NOT_CAPTURE
&H88781138 | DMUS_E_PORT_NOT_RENDER
&H88781139 | DMUS_E_DSOUND_NOT_SET
&H8878113A | DMUS_E_ALREADY_ACTIVATED
&H8878113B | DMUS_E_INVALIDBUFFER
&H8878113C | DMUS_E_WAVEFORMATNOTSUPPORTED
&H8878113D | DMUS_E_SYNTHINACTIVE
&H8878113E | DMUS_E_DSOUND_ALREADY_SET
&H8878113F | DMUS_E_INVALID_EVENT
&H88781150 | DMUS_E_UNSUPPORTED_STREAM
&H88781151 | DMUS_E_ALREADY_INITED
&H88781152 | DMUS_E_INVALID_BAND
&H88781155 | DMUS_E_TRACK_HDR_NOT_FIRST_CK
&H88781156 | DMUS_E_TOOL_HDR_NOT_FIRST_CK
&H88781157 | DMUS_E_INVALID_TRACK_HDR
&H88781158 | DMUS_E_INVALID_TOOL_HDR
&H88781159 | DMUS_E_ALL_TOOLS_FAILED
&H88781160 | DMUS_E_ALL_TRACKS_FAILED
&H88781161 | DMUS_E_NOT_FOUND
&H88781162 | DMUS_E_NOT_INIT
&H88781163 | DMUS_E_TYPE_DISABLED
&H88781164 | DMUS_E_TYPE_UNSUPPORTED
&H88781165 | DMUS_E_TIME_PAST
&H88781166 | DMUS_E_TRACK_NOT_FOUND
&H88781170 | DMUS_E_NO_MASTER_CLOCK
&H88781170 | DMUS_E_NOARTICULATION
&H88781180 | DMUS_E_LOADER_NOCLASSID
&H88781181 | DMUS_E_LOADER_BADPATH
&H88781182 | DMUS_E_LOADER_FAILEDOPEN
&H88781183 | DMUS_E_LOADER_FORMATNOTSUPPORTED
&H88781184 | DMUS_E_LOADER_FAILEDCREATE
&H88781185 | DMUS_E_LOADER_OBJECTNOTFOUND
&H88781186 | DMUS_E_LOADER_NOFILENAME
&H88781200 | DMUS_E_INVALIDFILE
&H88781201 | DMUS_E_ALREADY_EXISTS
&H88781202 | DMUS_E_OUT_OF_RANGE
&H88781203 | DMUS_E_SEGMENT_INIT_FAILED
&H88781204 | DMUS_E_ALREADY_SENT
&H88781205 | DMUS_E_CANNOT_FREE
&H88781206 | DMUS_E_CANNOT_OPEN_PORT
&H88781207 | DMUS_E_CANNOT_CONVERT
&H88781210 | DMUS_E_DESCEND_CHUNK_FAIL
&H88781211 | DMUS_E_NOT_LOADED
&H88781220 | DMUS_E_INVALID_SEGMENTTRIGGERTRACK
&H88781221 | DMUS_E_INVALID_LYRICSTRACK
&H88781222 | DMUS_E_INVALID_PARAMCONTROLTRACK
&H88781226 | DMUS_E_AUDIOPATHS_NOT_VALID
&H88781227 | DMUS_E_AUDIOPATHS_IN_USE
&H88781228 | DMUS_E_NO_AUDIOPATH_CONFIG
&H88781229 | DMUS_E_AUDIOPATH_INACTIVE
&H8878122A | DMUS_E_AUDIOPATH_NOBUFFER
&H8878122B | DMUS_E_AUDIOPATH_NOPORT
&H8878122C | DMUS_E_NO_AUDIOPATH


DirectMusic エラー コード (名前)

次のリストは、すべての DirectMusic エラー コードを示している。値から定数を確認するには、「DirectMusic エラー コード (値)」を参照すること。

DMUS_E_ALL_TOOLS_FAILED
グラフ オブジェクトは、すべてのツールをロードできなかった。これは、ストリーム内でエラーが発生したか、ツールがクライアント上で不正に登録されていることが原因と考えられる。
DMUS_E_ALL_TRACKS_FAILED
セグメント オブジェクトは、IStream オブジェクト データからすべてのトラックをロードできなかった。これは、ストリーム内でエラーが発生したか、トラックがクライアント上で不正に登録されていることが原因と考えられる。
DMUS_E_ALREADY_ACTIVATED
ポートは既にアクティブにされており、パラメータは変更できない。
DMUS_E_ALREADY_DOWNLOADED
バッファは既にダウンロードされている。
DMUS_E_ALREADY_EXISTS
ツールはグラフ内に既に含まれている。新しいインスタンスを作成しなければならない。
DMUS_E_ALREADY_INITED
オブジェクトは既に初期化されている。
DMUS_E_ALREADY_LOADED
DLS コレクションは既に開いている。
DMUS_E_ALREADY_SENT
メッセージは既に送信されている。
DMUS_E_ALREADYCLOSED
ポートは開いていない。
DMUS_E_ALREADYOPEN
ポートは既に開いていた。
DMUS_E_AUDIOPATH_INACTIVE
おそらくパフォーマンスが終了しているため、オーディオパスが非アクティブである。
DMUS_E_AUDIOPATH_NOBUFFER
要求されたバッファを作成できないため、オーディオパスを作成できなかった。
DMUS_E_AUDIOPATH_NOPORT
ポート割り当てがないため、再生にオーディオパスを使用できなかった。
DMUS_E_AUDIOPATHS_IN_USE
パフォーマンスがオーディオパスをセットアップしたので、パフォーマンス チャンネルを割り当てることができない。
DMUS_E_AUDIOPATHS_NOT_VALID
パフォーマンスはオーディオパスを使用していない。
DMUS_E_BADARTICULATION
DLS コレクション内に無効なアーティキュレーション チャンクがある。
DMUS_E_BADINSTRUMENT
DLS コレクション内に無効な音色チャンクがある。
DMUS_E_BADOFFSETTABLE
オフセット テーブルにエラーがある。
DMUS_E_BADWAVE
ウェーブ ヘッダーが壊れている。
DMUS_E_BADWAVELINK
DLS コレクション内のウェーブリンク チャンクが無効なウェーブを指している。
DMUS_E_BUFFER_EMPTY
バッファ内にデータがない。
DMUS_E_BUFFER_FULL
指定したバイト数が最大バッファ サイズを超えている。
DMUS_E_BUFFERNOTAVAILABLE
このバッファはダウンロードに利用できない。
DMUS_E_BUFFERNOTSET
データ用に準備されたバッファが存在しない。
DMUS_E_CANNOT_CONVERT
ミュージック値と MIDI 値との間で要求した変換は行われなかった。
DMUS_E_CANNOT_FREE
メッセージが割り当てられていないか、既に解放されているため、メッセージを解放できなかった。
DMUS_E_CANNOT_OPEN_PORT
デフォルトのシステム ポートを開くことができなかった。
DMUS_E_CANNOTREAD
IStream オブジェクトから読み込みを行おうとしていたときにエラーが発生した。
DMUS_E_CANNOTSEEK
ストリーム オブジェクトはシークをサポートしていない。
DMUS_E_CANNOTWRITE
ストリーム オブジェクトは書き込みをサポートしていない。
DMUS_E_CHUNKNOTFOUND
指定されたヘッダーを持つチャンクが見つからなかった。
DMUS_E_DESCEND_CHUNK_FAIL
チャンク内に下がろうとしたが失敗した。
DMUS_E_DEVICE_IN_USE
(おそらく DirectMusic 以外のクライアントによって) デバイスは既に使われており、再度開くことができない。
DMUS_E_DMUSIC_RELEASED
DirectMusic オブジェクトの最後のインスタンスが解放されたため、操作を実行できない。DirectMusic オブジェクトの最後の解放が終わるまで、ポートは使用できない。
DMUS_E_DRIVER_FAILED
ドライバまたはハードウェアでの障害の可能性を示す予想外のエラーがデバイス ドライバから返された。
DMUS_E_DSOUND_ALREADY_SET
DirectSound オブジェクトは既に設定されている。
DMUS_E_DSOUND_NOT_SET
DirectSound オブジェクトが指定されていないため、ポートを作成できなかった。
DMUS_E_FAIL
このメソッドは成功しなかった。
DMUS_E_GET_UNSUPPORTED
パラメータの取得はサポートしていない。
DMUS_E_INSUFFICIENTBUFFER
要求された操作を実行するためのバッファが十分な大きさではない。
DMUS_E_INVALID_BAND
ファイルに有効なバンドが含まれていない。
DMUS_E_INVALID_DOWNLOADID
ダウンロード バッファの作成プロセスで、無効なダウンロード識別子が使われた。
DMUS_E_INVALID_EVENT
イベントは、有効な MIDI メッセージではない、または動作ステータスを利用しておりバッファ内にパックできない。
DMUS_E_INVALID_LYRICSTRACK
ファイルに含まれる歌詞トラックが無効である。
DMUS_E_INVALID_PARAMCONTROLTRACK
ファイルに含まれるパラメータ制御トラックが無効である。
DMUS_E_INVALID_SEGMENTTRIGGERTRACK
ファイルに含まれるセグメント トリガ トラックが無効である。
DMUS_E_INVALID_TOOL_HDR
ストリーム オブジェクトのデータに含まれるツール ヘッダーが無効であるため、グラフ オブジェクトによる読み込みができない。
DMUS_E_INVALID_TRACK_HDR
ストリーム オブジェクトのデータに含まれるトラック ヘッダーが無効であるため、セグメント オブジェクトによる読み込みができない。
DMUS_E_INVALIDARG
無効な値がパラメータに渡された。
DMUS_E_INVALIDBUFFER
無効な DirectSound バッファがポートに渡された。
DMUS_E_INVALIDFILE
ファイルが無効である。
DMUS_E_INVALIDOFFSET
DLS コレクション ファイル内のウェーブ チャンクが、正しいオフセット上にない。
DMUS_E_INVALIDPATCH
コレクション内の音色がパッチ番号と一致しない。
DMUS_E_INVALIDPOS
DLS コレクションからウェーブ データを読み込み中にエラーが発生した。これは、不正なファイルであることを意味する。
DMUS_E_LOADER_BADPATH
ファイルパスが無効である。
DMUS_E_LOADER_FAILEDCREATE
オブジェクトが見つからなかった、または作成できなかった。
DMUS_E_LOADER_FAILEDOPEN
ファイルが存在していないかロックされているのが原因で、ファイルを開くことに失敗した。
DMUS_E_LOADER_FORMATNOTSUPPORTED
データ形式がサポートされていないため、オブジェクトをロードできない。
DMUS_E_LOADER_NOCLASSID
オブジェクト記述にクラス識別子が指定されていない。
DMUS_E_LOADER_NOFILENAME
オブジェクト記述にファイル名が指定されていない。
DMUS_E_LOADER_OBJECTNOTFOUND
オブジェクトが見つからなかった。
DMUS_E_NO_AUDIOPATH
存在しないオーディオパス上で演奏しようとした。
DMUS_E_NO_AUDIOPATH_CONFIG
セグメントに、埋め込み型のオーディオパス構成が含まれていない。
DMUS_E_NO_MASTER_CLOCK
パフォーマンスにマスタ クロックがない。これは、DirectMusicPerformance8.InitAudio メソッドが呼び出されなかったことが原因と考えられる。
DMUS_E_NOARTICULATION
DLS コレクション内の音色からアーティキュレーションが見つからない。
DMUS_E_NOINTERFACE
利用可能なオブジェクト インターフェイスがない。
DMUS_E_NOSYNTHSINK
シンクがシンセサイザに接続されていない。
DMUS_E_NOT_DOWNLOADED_TO_PORT
オブジェクトがポート上にないため、アンロードできない。
DMUS_E_NOT_FOUND
要求された項目はオブジェクトに含まれていない。
DMUS_E_NOT_INIT
必要なオブジェクトは初期化されていないか、初期化に失敗した。
DMUS_E_NOT_LOADED
このオブジェクトがロードされていなかったため、使用できなかった。
DMUS_E_NOTADLSCOL
ロード中のオブジェクトは有効な DLS コレクションではない。
DMUS_E_NOTIMPL
このメソッドは実装されていない。動作に必要な機能をドライバがサポートしていないために、この値が返されることがある。
DMUS_E_NOTMONO
ウェーブ チャンクには複数のインターリーブ チャンネルがある。DLS フォーマットではモノラルが要求される。
DMUS_E_NOTPCM
ウェーブ データが PCM フォーマットではない。
DMUS_E_OUT_OF_RANGE
要求されたタイムはセグメントの範囲外である。
DMUS_E_OUTOFMEMORY
メモリ不足のため、タスクを完了できない。
DMUS_E_PORT_NOT_CAPTURE
ポートはキャプチャ ポートではない。
DMUS_E_PORT_NOT_RENDER
出力ポートではない。
DMUS_E_PORTS_OPEN
システム内の任意のプロセスにインスタンス化されたポートがあるときは、要求された操作を実行できない。
DMUS_E_SEGMENT_INIT_FAILED
セグメントの初期化に失敗した。メモリで重大な問題が発生したと考えられる。
DMUS_E_SET_UNSUPPORTED
パラメータの設定はサポートしていない。
DMUS_E_SYNTHACTIVE
シンセサイザは既にアクティブにされており、パラメータは変更できない。
DMUS_E_SYNTHINACTIVE
シンセサイザはアクティブにされておらず、データを処理できない。
DMUS_E_SYNTHNOTCONFIGURED
シンセサイザは正しく構成されていないか、開いていない。
DMUS_E_TIME_PAST
要求されたタイムは過去のタイムである。
DMUS_E_TOOL_HDR_NOT_FIRST_CK
ストリーム オブジェクトのデータには最初のチャンクとしてツール ヘッダーがないため、グラフ オブジェクトによる読み込みができない。
DMUS_E_TRACK_HDR_NOT_FIRST_CK
ストリーム オブジェクトのデータには最初のチャンクとしてトラック ヘッダーがないため、セグメント オブジェクトによる読み込みができない。
DMUS_E_TRACK_NOT_FOUND
要求されたタイプのトラックがない。
DMUS_E_TYPE_DISABLED
パラメータは無効にされているため利用できない。
DMUS_E_TYPE_UNSUPPORTED
パラメータはこのトラック上でサポートされていない。
DMUS_E_UNKNOWN_PROPERTY
このポートにはプロパティ セットや項目が実装されていない。
DMUS_E_UNKNOWNDOWNLOAD
シンセサイザはこのタイプのダウンロードをサポートしていない。
DMUS_E_UNSUPPORTED_STREAM
ストリームは、ロード中のオブジェクトがサポートしているデータを含んでいない。
DMUS_E_WAVEFORMATNOTSUPPORTED
シンセサイザ シンクに渡されたバッファ フォーマットが無効である。


DirectSound Visual Basic リファレンス

ここでは、Microsoft® Visual Basic® における Microsoft® DirectSound® の API 要素のリファレンス情報を記述する。リファレンス情報は次のカテゴリに分類されている。

  • DirectSound クラス
  • DirectSound の型
  • DirectSound の列挙
  • DirectSound のエラー コード


DirectSound クラス

ここでは、次の DirectSound クラスのリファレンス情報を記述する。

  • DirectSound3DBuffer8
  • DirectSound3DListener8
  • DirectSound8
  • DirectSoundCapture8
  • DirectSoundCaptureBuffer8
  • DirectSoundEnum8
  • DirectSoundFXChorus8
  • DirectSoundFXCompressor8
  • DirectSoundFXDistortion8
  • DirectSoundFXEcho8
  • DirectSoundFXFlanger8
  • DirectSoundFXGargle8
  • DirectSoundFXI3DL2Reverb8
  • DirectSoundFXParamEq8
  • DirectSoundFXWavesReverb8
  • DirectSoundPrimaryBuffer8
  • DirectSoundSecondaryBuffer8


DirectSound3DBuffer8

3D 空間のサウンド バッファの位置、向き、およびその他のパラメータの設定および取得に使用する。

DirectSound3DBuffer8 オブジェクトは、3D 能力で作成されたセカンダリ バッファの DirectSoundSecondaryBuffer8.GetDirectSound3DBuffer メソッドを使って取得する。このオブジェトは、オーディオパスから取得することもできる。

DirectSound3DBuffer8 クラスのメソッドは、次のグループにまとめることができる。

バッチ パラメータ操作 | GetAllParameters
 | SetAllParameters
距離 | GetMaxDistance
 | GetMinDistance
 | SetMaxDistance
 | SetMinDistance
オブジェクトの取得 | GetDirectSoundBuffer
操作モード | GetMode
 | SetMode
位置 | GetPosition
 | SetPosition
サウンド プロジェクション コーン | GetConeAngles
 | GetConeOrientation
 | GetConeOutsideVolume
 | SetConeAngles
 | SetConeOrientation
 | SetConeOutsideVolume
速度 | GetVelocity
 | SetVelocity

参照

3D バッファ オブジェクトの取得


DirectSound3DBuffer8.GetAllParameters

サウンド バッファの 3D 特性に関する情報を取得する。

object.GetAllParameters(buffer As DS3DBUFFER)

指定項目

object
DirectSound3DBuffer8 オブジェクトを指定する。
buffer
サウンド バッファの 3D 特性の記述を受け取る DS3DBUFFER 型。

エラー コード

失敗した場合はエラーが発生し、Err.Number に DSERR_INVALIDPARAM が設定される。


DirectSound3DBuffer8.GetConeAngles

サウンド バッファのサウンド プロジェクション コーンの内部角度と外部角度を取得する。

object.GetConeAngles( _
  inCone As Long, _
  outCone As Long)

指定項目

object
DirectSound3DBuffer8 オブジェクトを指定する。
inCone
サウンド プロジェクション コーンの内部角度を受け取る変数。単位は度 (°)。
outCone
サウンド プロジェクション コーンの外部角度を受け取る変数。単位は度 (°)。

エラー コード

失敗した場合はエラーが発生し、Err.Number に DSERR_INVALIDPARAM が設定される。

注意

最小、最大、デフォルトの各コーン角度はそれぞれ、DS3D_MINCONEANGLE、DS3D_MAXCONEANGLE、DS3D_DEFAULTCONEANGLE として定義される。

参照

サウンド コーン


DirectSound3DBuffer8.GetConeOrientation

サウンド バッファのサウンド プロジェクション コーンの向きを取得する。

object.GetConeOrientation(orientation As D3DVECTOR)

指定項目

object
DirectSound3DBuffer8 オブジェクトを指定する。
orientation
サウンド プロジェクション コーンの現在の向きを受け取る D3DVECTOR 型。ベクトル情報はサウンド コーンの中心を表す。

エラー コード

失敗した場合はエラーが発生し、Err.Number に DSERR_INVALIDPARAM が設定される。

注意

戻り値は必ずしも DirectSound3DBuffer8.SetConeOrientation メソッドを使って設定した場合と同じ値ではない。DirectSound は向きベクトルに調整を加え、それらのマグニチュードを 1.0 以下にする。

参照

サウンド コーン


DirectSound3DBuffer8.GetConeOutsideVolume

サウンド バッファの現在のコーン外部ボリュームを取得する。

object.GetConeOutsideVolume() As Long

指定項目

object
DirectSound3DBuffer8 オブジェクトを指定する。

戻り値

サウンド バッファの現在のコーン外部ボリュームを返す。

エラー コード

失敗した場合はエラーが発生し、Err.Number に DSERR_INVALIDPARAM が設定される。

注意

ボリューム レベルは減衰によって表される。設定可能な値は DSBVOLUME_MAX (減衰なし) と DSBVOLUME_MIN (無音) の間である。デフォルト値は DS3D_DEFAULTCONEOUTSIDEVOLUME (減衰なし) である。DirectSound は増幅をサポートしていない。

参照

サウンド コーン


DirectSound3DBuffer8.GetDirectSoundBuffer

3D バッファが作成されたセカンダリ バッファを返す。

object.GetDirectSoundBuffer() As DirectSoundSecondaryBuffer8

指定項目

object
DirectSound3DBuffer8 オブジェクトを指定する。

戻り値

DirectSoundSecondaryBuffer8 オブジェクトを返す。

エラー コード

失敗した場合はエラーが発生し、Err.Number が設定される。

注意

このメソッドは、DirectSound3DBuffer8 オブジェクトを作成した DirectSoundSecondaryBuffer8 オブジェクトが利用できない場合に、DirectSoundSecondaryBuffer8 オブジェクトを取得するために使用する。


DirectSound3DBuffer8.GetMaxDistance

サウンド バッファの現在の最大距離を取得する。これは、ボリュームがそれ以上減衰しなくなる距離である。

object.GetMaxDistance() As Single

指定項目

object
DirectSound3DBuffer8 オブジェクトを指定する。

戻り値

現在の最大距離の設定を返す。

エラー コード

失敗した場合はエラーが発生し、Err.Number に DSERR_INVALIDPARAM が設定される。

注意

デフォルトの最大距離は DS3D_DEFAULTMAXDISTANCE によって定義され、実質的に無限大である。

参照

DirectSound3DBuffer8.GetMinDistance、DirectSound3DBuffer8.SetMaxDistance、最小距離と最大距離


DirectSound3DBuffer8.GetMinDistance

サウンド バッファの現在の最小距離を取得する。これは、サウンドが最大ボリュームとなる距離である。

object.GetMinDistance() As Single

指定項目

object
DirectSound3DBuffer8 オブジェクトを指定する。

戻り値

最小距離の設定を返す。

エラー コード

失敗した場合はエラーが発生し、Err.Number に DSERR_INVALIDPARAM が設定される。

注意

デフォルトでは、最小距離値は DS3D_DEFAULTMINDISTANCE であり、現在は 1.0 と定義されている (デフォルトの距離係数 1.0 を使った場合、1 単位は 1.0 メートルに相当する)。

参照

DirectSound3DBuffer8.SetMinDistance、DirectSound3DBuffer8.GetMaxDistance、最小距離と最大距離


DirectSound3DBuffer8.GetMode

3D サウンド処理の現在の操作モードを取得する。

object.GetMode() As CONST_DS3DMODEFLAGS

指定項目

object
DirectSound3DBuffer8 オブジェクトを指定する。

戻り値

モード設定を返す。この値は、CONST_DS3DMODEFLAGS 列挙の定数のいずれかである。

エラー コード

失敗した場合はエラーが発生し、Err.Number に DSERR_INVALIDPARAM が設定される。


DirectSound3DBuffer8.GetPosition

サウンド バッファの位置を距離単位で取得する。

object.GetPosition(position As D3DVECTOR)

指定項目

object
DirectSound3DBuffer8 オブジェクトを指定する。
position
サウンド バッファの位置を受け取る D3DVECTOR 型。

エラー コード

失敗した場合はエラーが発生し、Err.Number に DSERR_INVALIDPARAM が設定される。

注意

デフォルトでは、距離単位はメートルであるが、DirectSound3DListener8.SetDistanceFactor メソッドを使用して単位を変更できる。


DirectSound3DBuffer8.GetVelocity

サウンド バッファの現在の速度を取得する。

object.GetVelocity(velocity As D3DVECTOR)

指定項目

object
DirectSound3DBuffer8 オブジェクトを指定する。
velocity
サウンド バッファの現在の速度を受け取る D3DVECTOR 型。

エラー コード

失敗した場合はエラーが発生し、Err.Number に DSERR_INVALIDPARAM が設定される。

注意

速度はドップラー効果でのみ使用される。バッファを移動することはない。

デフォルトの計測単位はメートル/秒であるが、DirectSound3DListener8.SetDistanceFactor メソッドを使用して変更できる。

参照

DirectSound3DBuffer8.SetPosition、DirectSound3DBuffer8.SetVelocity、ドップラー係数


DirectSound3DBuffer8.SetAllParameters

サウンド バッファのすべての 3D プロパティを設定する。

object.SetAllParameters( _
  buffer As DS3DBUFFER, _
  applyFlag As CONST_DS3DAPPLYFLAGS)

指定項目

object
DirectSound3DBuffer8 オブジェクトを指定する。
buffer
サウンド バッファの 3D 特性を記述する情報を保持する DS3DBUFFER 型。
applyFlag
設定が適用されるタイミングを指定する値。この値は、CONST_DS3DAPPLYFLAGS 列挙の定数のいずれかでなければならない。

エラー コード

失敗した場合はエラーが発生し、Err.Number に DSERR_INVALIDPARAM が設定される。


DirectSound3DBuffer8.SetConeAngles

サウンド バッファのサウンド プロジェクション コーンの内部角度と外部角度を設定する。

object.SetConeAngles( _
  inCone As Long, _
  outCone As Long, _
  applyFlag As CONST_DS3DAPPLYFLAGS)

指定項目

object
DirectSound3DBuffer8 オブジェクトを指定する。
inCone
サウンド プロジェクション コーンの内部角度。単位は度 (°)。
outCone
サウンド プロジェクション コーンの外部角度。単位は度 (°)。
applyFlag
設定が適用されるタイミングを指定する値。この値には、CONST_DS3DAPPLYFLAGS 列挙の定数のいずれかを指定する必要がある。

エラー コード

失敗した場合はエラーが発生し、Err.Number に DSERR_INVALIDPARAM が設定される。

注意

最小、最大、デフォルトの各コーン角度はそれぞれ、DS3D_MINCONEANGLE、DS3D_MAXCONEANGLE、DS3D_DEFAULTCONEANGLE として定義される。各角度の範囲は、0° (コーンなし) から 360° (全範囲) までである。デフォルト値は 360 である。

参照

サウンド コーン


DirectSound3DBuffer8.SetConeOrientation

サウンド バッファのサウンド プロジェクション コーンの向きを設定する。コーン角度とコーン ボリューム係数が既に設定されていない限り、このメソッドは何もしない。

object.SetConeOrientation( _
  x As Single, _
  y As Single, _
  z As Single, _
  applyFlag As CONST_DS3DAPPLYFLAGS)

指定項目

object
DirectSound3DBuffer8 オブジェクトを指定する。
x、y、z
サウンド コーンの新しい向きベクトルの座標。
applyFlag
設定が適用されるタイミングを指定する値。CONST_DS3DAPPLYFLAGS 列挙の定数のいずれかを指定する必要がある。

エラー コード

失敗した場合はエラーが発生し、Err.Number に DSERR_INVALIDPARAM が設定される。

参照

サウンド コーン


DirectSound3DBuffer8.SetConeOutsideVolume

サウンド バッファのコーン外部ボリュームを設定する。

object.SetConeOutsideVolume( _
  coneOutsideVolume As Long, _
  applyFlag As CONST_DS3DAPPLYFLAGS)

指定項目

object
DirectSound3DBuffer8 オブジェクトを指定する。
coneOutsideVolume
サウンド バッファのコーン外部ボリュームを 100 分の 1 デシベル (dB) の単位で指定する。
applyFlag
設定が適用されるタイミングを指定する値。CONST_DS3DAPPLYFLAGS 列挙の定数のいずれかを指定する必要がある。

エラー コード

失敗した場合はエラーが発生し、Err.Number に DSERR_INVALIDPARAM が設定される。

注意

ボリューム レベルは減衰によって表される。設定可能な値は DSBVOLUME_MAX (減衰なし) と DSBVOLUME_MIN (無音) の間である。デフォルト値は DS3D_DEFAULTCONEOUTSIDEVOLUME (減衰なし) である。

参照

DirectSoundSecondaryBuffer8.SetVolume、サウンド コーン


DirectSound3DBuffer8.SetMaxDistance

バッファの最大距離を設定する。これは、サウンドがそれ以上減衰しなくなる距離である。

object.SetMaxDistance( _
  maxDistance As Single, _
  applyFlag As CONST_DS3DAPPLYFLAGS)

指定項目

object
DirectSound3DBuffer8 オブジェクトを指定する。
maxDistance
最大距離値。
applyFlag
設定が適用されるタイミングを指定する値。CONST_DS3DAPPLYFLAGS 列挙の定数のいずれかを指定する必要がある。

エラー コード

失敗した場合はエラーが発生し、Err.Number に DSERR_INVALIDPARAM が設定される。

注意

デフォルトの最大距離は DS3D_DEFAULTMAXDISTANCE によって定義され、実質的に無限大である。

参照

DirectSound3DBuffer8.GetMaxDistance、DirectSound3DBuffer8.SetMinDistance、最小距離と最大距離


DirectSound3DBuffer8.SetMinDistance

バッファの最小距離を設定する。これは、サウンドが最大ボリュームとなる距離である。

object.SetMinDistance( _
  minDistance As Single, _
  applyFlag As CONST_DS3DAPPLYFLAGS)

指定項目

object
DirectSound3DBuffer8 オブジェクトを指定する。
minDistance
最小距離値。
applyFlag
設定が適用されるタイミングを指定する値。CONST_DS3DAPPLYFLAGS 列挙の定数のいずれかを指定する必要がある。

エラー コード

失敗した場合はエラーが発生し、Err.Number に DSERR_INVALIDPARAM が設定される。

注意

デフォルトでは、最小距離値は DS3D_DEFAULTMINDISTANCE であり、1.0 と定義されている (デフォルトの距離係数 1.0 を使った場合、1 単位は 1.0 メートルに相当する)。

参照

DirectSound3DBuffer8.SetMaxDistance、最小距離と最大距離


DirectSound3DBuffer8.SetMode

3D サウンド処理の操作モードを設定する。

object.SetMode( _
  mode As CONST_DS3DMODEFLAGS, _
  applyFlag As CONST_DS3DAPPLYFLAGS)

指定項目

object
DirectSound3DBuffer8 オブジェクトを指定する。
mode
設定する 3D サウンド処理モードを指定する CONST_DS3DMODEFLAGS 列挙の定数の 1 つを指定する。
applyFlag
設定が適用されるタイミングを指定する値。CONST_DS3DAPPLYFLAGS 列挙の定数のいずれかを指定する必要がある。

エラー コード

失敗した場合はエラーが発生し、Err.Number に DSERR_INVALIDPARAM が設定される。


DirectSound3DBuffer8.SetPosition

サウンド バッファの位置を距離単位で設定する。

object.SetPosition( _
  x As Single, _
  y As Single, _
  z As Single, _
  applyFlag As CONST_DS3DAPPLYFLAGS)

指定項目

object
DirectSound3DBuffer8 オブジェクトを指定する。
x、y、z
位置ベクトルの座標を指定する値。浮動小数点のオーバーフローを防ぐために、DirectSound でこれらの値が調整される場合がある。
applyFlag
設定が適用されるタイミングを指定する値。CONST_DS3DAPPLYFLAGS 列挙の定数のいずれかを指定する必要がある。

エラー コード

失敗した場合はエラーが発生し、Err.Number に DSERR_INVALIDPARAM が設定される。

注意

デフォルトでは、距離単位はメートルであるが、DirectSound3DListener8.SetDistanceFactor メソッドを使用して単位を変更できる。


DirectSound3DBuffer8.SetVelocity

サウンド バッファの速度を設定する。

object.SetVelocity( _
  x As Single, _
  y As Single, _
  z As Single, _
  applyFlag As CONST_DS3DAPPLYFLAGS)

指定項目

object
DirectSound3DBuffer8 オブジェクトを指定する。
x、y、z
速度ベクトルの座標を指定する値。浮動小数点のオーバーフローを防ぐために、DirectSound でこれらの値が調整される場合がある。
applyFlag
設定が適用されるタイミングを指定する値。CONST_DS3DAPPLYFLAGS 列挙の定数のいずれかを指定する必要がある。

エラー コード

失敗した場合はエラーが発生し、Err.Number に DSERR_INVALIDPARAM が設定される。

注意

速度はドップラー効果でのみ使用される。バッファを移動することはない。

デフォルトの計測単位はメートル/秒であるが、DirectSound3DListener8.SetDistanceFactor メソッドを使用して変更できる。

参照

DirectSound3DBuffer8.SetPosition、DirectSound3DBuffer8.GetVelocity、バッファの位置座標と速度


DirectSound3DListener8

リスナーの位置と向きを表し、グローバル 3D サウンド パラメータを制御する。

DirectSoundPrimaryBuffer8.GetDirectSound3DListener メソッドを使って、DirectSound3DListener8 クラスのオブジェクトを取得する。

DirectSound3DListener8 クラスのメソッドは、次のグループにまとめることができる。

バッチ パラメータ | GetAllParameters
 | SetAllParameters
遅延設定 | CommitDeferredSettings
距離係数 | GetDistanceFactor
 | SetDistanceFactor
ドップラー係数 | GetDopplerFactor
 | SetDopplerFactor
オブジェクトの取得 | GetDirectSoundBuffer
方向 | GetOrientation
 | SetOrientation
位置 | GetPosition
 | SetPosition
ロールオフ係数 | GetRolloffFactor
 | SetRolloffFactor
速度 | GetVelocity
 | SetVelocity


DirectSound3DListener8.CommitDeferredSettings

DS3D_DEFERRED フラグを DirectSound3DBuffer8 および DirectSound3DListener8 のメソッドに渡して行われた、すべてのパラメータ変更をコミットする。

object.CommitDeferredSettings()

指定項目

object
DirectSound3DListener8 オブジェクトを表す。

エラー コード

失敗した場合はエラーが発生し、Err.Number に DSERR_INVALIDPARAM が設定される。

参照

遅延設定


DirectSound3DListener8.GetAllParameters

3D ワールドとリスナーの状態を取得する。

object.GetAllParameters(listener As DS3DLISTENER)

指定項目

object
DirectSound3DListener8 オブジェクトを指定する。
listener
パラメータを受け取る DS3DLISTENER 型。

エラー コード

失敗した場合はエラーが発生し、Err.Number に DSERR_INVALIDPARAM が設定される。

参照

DirectSound3DListener8.SetAllParameters


DirectSound3DListener8.GetDirectSoundBuffer

リスナーが作成されたプライマリ バッファを取得する。

object.GetDirectSoundBuffer() As DirectSoundPrimaryBuffer8

指定項目

object
DirectSound3DListener8 オブジェクトを指定する。

戻り値

DirectSoundPrimaryBuffer8 オブジェクトを返す。

エラー コード

失敗すればエラーが発生し、Err.Number に DSERR_OUTOFMEMORY が設定される。


DirectSound3DListener8.GetDistanceFactor

ベクトル単位のメートル数で距離係数を取得する。

object.GetDistanceFactor() As Single

指定項目

object
DirectSound3DListener8 オブジェクトを指定する。

戻り値

距離係数を返す。

エラー コード

失敗した場合はエラーが発生し、Err.Number に DSERR_INVALIDPARAM が設定される。

参照

DirectSound3DListener8.SetDistanceFactor、距離係数


DirectSound3DListener8.GetDopplerFactor

ドップラー効果係数を取得する。

object.GetDopplerFactor() As Single

指定項目

object
DirectSound3DListener8 オブジェクトを指定する。

戻り値

ドップラー係数を返す。

エラー コード

失敗した場合はエラーが発生し、Err.Number に DSERR_INVALIDPARAM が設定される。

注意

ドップラー係数の範囲は、DS3D_MINDOPPLERFACTOR (ドップラー効果なし) から DS3D_MAXDOPPLERFACTOR (実世界の 10 倍のドップラー効果) までである。デフォルト値は DS3D_DEFAULTDOPPLERFACTOR (1.0) である。

参照

DirectSound3DListener8.SetDopplerFactor、ドップラー係数


DirectSound3DListener8.GetOrientation

3D 空間におけるリスナーの向きを取得する。

object.GetOrientation( _
  orientFront As D3DVECTOR, _
  orientTop As D3DVECTOR)

指定項目

object
DirectSound3DListener8 オブジェクトを指定する。
orientFront
リスナーの前方ベクトルを受け取る D3DVECTOR 型。
orientTop
リスナーの上方ベクトルを受け取る D3DVECTOR 型。

エラー コード

失敗した場合はエラーが発生し、Err.Number に DSERR_INVALIDPARAM が設定される。

注意

前方ベクトルはリスナーの鼻の方向、上方ベクトルはリスナーの頭頂部の方向を指す。デフォルトでは、前方ベクトルが (0,0,1.0)、上方ベクトルが (0,1.0,0) である。

戻り値は必ずしも DirectSound3DListener8.SetOrientation メソッドを使って設定した場合と同じ値ではない。DirectSound は向きベクトルに調整を加え、それらが互いに直角になるようにし、両方のマグニチュードを 1.0 以下にする。

参照

リスナーの向き


DirectSound3DListener8.GetPosition

3D 空間におけるリスナーの位置を取得する。

object.GetPosition(position As D3DVECTOR)

指定項目

object
DirectSound3DListener8 オブジェクトを指定する。
position
リスナーの位置ベクトルを受け取る D3DVECTOR 型。

エラー コード

失敗すればエラーが発生し、Err.Number に DSERR_INVALIDPARAM が設定される。

参照

DirectSound3DListener8.SetPosition、リスナーの位置座標と速度


DirectSound3DListener8.GetRolloffFactor

距離に応じた減衰率を制御するロールオフ係数を取得する。

object.GetRolloffFactor() As Single

指定項目

object
DirectSound3DListener8 オブジェクトを指定する。

戻り値

ロールオフ係数を返す。

エラー コード

失敗した場合はエラーが発生し、Err.Number に DSERR_INVALIDPARAM が設定される。

注意

ロールオフ係数は、DS3D_MINROLLOFFFACTOR (ロールオフなし) から DS3D_MAXROLLOFFFACTOR (実世界の 10 倍のロールオフ) までの範囲をとる。デフォルト値は DS3D_DEFAULTROLLOFFFACTOR (1.0) である。

参照

DirectSound3DListener8.SetRolloffFactor、ロールオフ係数


DirectSound3DListener8.GetVelocity

リスナーの速度を取得する。

object.GetVelocity() As D3DVECTOR

指定項目

object
DirectSound3DListener8 オブジェクトを指定する。

戻り値

リスナーの速度を保持する D3DVECTOR 型を返す。

エラー コード

失敗した場合はエラーが発生し、Err.Number に DSERR_INVALIDPARAM が設定される。

注意

デフォルトの速度は (0,0,0) である。

速度はドップラー効果でのみ使用される。リスナーを移動することはない。

参照

DirectSound3DListener8.SetVelocity、リスナーの位置座標と速度


DirectSound3DListener8.SetAllParameters

すべての 3D リスナーのプロパティとグローバル サウンド パラメータを設定する。

object.SetAllParameters( _
  listener As DS3DLISTENER, _
  applyFlag As CONST_DS3DAPPLYFLAGS)

指定項目

object
DirectSound3DListener8 オブジェクトを指定する。
listener
すべての 3D リスナーのパラメータ情報を保持する DS3DLISTENER 型。
applyFlag
設定が適用されるタイミングを指定する値。この値には、CONST_DS3DAPPLYFLAGS 列挙の定数のいずれかを指定する必要がある。

エラー コード

失敗した場合はエラーが発生し、Err.Number に DSERR_INVALIDPARAM が設定される。

参照

DirectSound3DListener8.GetAllParameters


DirectSound3DListener8.SetDistanceFactor

ベクトル単位のメートル数で距離係数を設定する。

object.SetDistanceFactor( _
  distanceFactor As Single, _
  applyFlag As CONST_DS3DAPPLYFLAGS)

指定項目

object
DirectSound3DListener8 オブジェクトを指定する。
distanceFactor
距離係数。
applyFlag
設定が適用されるタイミングを指定する値。この値には、CONST_DS3DAPPLYFLAGS 列挙の定数のいずれかを指定する必要がある。

エラー コード

失敗した場合はエラーが発生し、Err.Number に DSERR_INVALIDPARAM が設定される。

参照

DirectSound3DListener8.GetDistanceFactor、距離係数


DirectSound3DListener8.SetDopplerFactor

ドップラー効果係数を設定する。

object.SetDopplerFactor( _
  dopplerFactor As Single, _
  applyFlag As CONST_DS3DAPPLYFLAGS)

指定項目

object
DirectSound3DListener8 オブジェクトを指定する。
dopplerFactor
ドップラー係数の値。
applyFlag
設定が適用されるタイミングを指定する値。CONST_DS3DAPPLYFLAGS 列挙の定数のいずれかを指定する必要がある。

エラー コード

失敗した場合はエラーが発生し、Err.Number に DSERR_INVALIDPARAM が設定される。

注意

ドップラー係数の範囲は、DS3D_MINDOPPLERFACTOR (ドップラー効果なし) から DS3D_MAXDOPPLERFACTOR (実世界の 10 倍のドップラー効果) までである。デフォルト値は DS3D_DEFAULTDOPPLERFACTOR (1.0) である。

参照

DirectSound3DListener8.GetDopplerFactor、ドップラー係数


DirectSound3DListener8.SetOrientation

前方ベクトルと上方ベクトルの 2 つのベクトルにより、リスナーの向きを設定する。

object.SetOrientation( _
  xFront As Single, _
  yFront As Single, _
  zFront As Single, _
  xTop As Single, _
  yTop As Single, _
  zTop As Single, _
  applyFlag As CONST_DS3DAPPLYFLAGS)

指定項目

object
DirectSound3DListener8 オブジェクトを指定する。
xFront、yFront、zFront
前方ベクトルの座標を指定する値。
xTop、yTop、zTop
上方ベクトルの座標を指定する値。
applyFlag
設定が適用されるタイミングを指定する値。CONST_DS3DAPPLYFLAGS 列挙の定数のいずれかを指定する必要がある。

エラー コード

失敗した場合はエラーが発生し、Err.Number に DSERR_INVALIDPARAM が設定される。

注意

前方ベクトルはリスナーの鼻の方向、上方ベクトルはリスナーの頭頂部の方向を指す。デフォルトでは、前方ベクトルが (0,0,1.0)、上方ベクトルが (0,1.0,0) である。

上方ベクトルは前方ベクトルに対して直角でなければならない。必要に応じて、DirectSound は前方ベクトルを設定した後で上方ベクトルを調整する。

参照

DirectSound3DListener8.GetOrientation、リスナーの向き


DirectSound3DListener8.SetPosition

リスナーの位置を距離単位で設定する。

object.SetPosition( _
  x As Single, _
  y As Single, _
  z As Single, _
  applyFlag As CONST_DS3DAPPLYFLAGS)

指定項目

object
DirectSound3DListener8 オブジェクトを指定する。
x、y、z
リスナーの位置ベクトルの座標を指定する値。浮動小数点のオーバーフローを防ぐために、DirectSound でこれらの値が調整される場合がある。
applyFlag
設定が適用されるタイミングを指定する値。CONST_DS3DAPPLYFLAGS 列挙の定数のいずれかを指定する必要がある。

エラー コード

失敗した場合はエラーが発生し、Err.Number に DSERR_INVALIDPARAM が設定される。

注意

デフォルトではこれらの単位はメートルだが、DirectSound3DListener8.SetDistanceFactor メソッドを使って単位を変更できる。

参照

DirectSound3DListener8.GetPosition、リスナーの位置座標と速度


DirectSound3DListener8.SetRolloffFactor

距離に応じた減衰率を決定するロールオフ係数を設定する。

object.SetRolloffFactor( _
  rolloffFactor As Single, _
  applyFlag As CONST_DS3DAPPLYFLAGS)

指定項目

object
DirectSound3DListener8 オブジェクトを指定する。
rolloffFactor
ロールオフ係数。
applyFlag
設定が適用されるタイミングを指定する値。CONST_DS3DAPPLYFLAGS 列挙の定数のいずれかを指定する必要がある。

エラー コード

失敗した場合はエラーが発生し、Err.Number に DSERR_INVALIDPARAM が設定される。

注意

ロールオフ係数は、DS3D_MINROLLOFFFACTOR (ロールオフなし) から DS3D_MAXROLLOFFFACTOR (実世界の 10 倍のロールオフ) までの範囲をとる。デフォルト値は DS3D_DEFAULTROLLOFFFACTOR (1.0) である。

参照

DirectSound3DListener8.GetRolloffFactor、ロールオフ係数


DirectSound3DListener8.SetVelocity

リスナーの速度を設定する。

object.SetVelocity( _
  x As Single, _
  y As Single, _
  z As Single, _
  applyFlag As CONST_DS3DAPPLYFLAGS)

指定項目

object
DirectSound3DListener8 オブジェクトを指定する。
x、y、z
リスナーの速度ベクトルの座標を指定する値。浮動小数点のオーバーフローを防ぐために、DirectSound でこれらの値が調整される場合がある。
applyFlag
設定が適用されるタイミングを指定する値。CONST_DS3DAPPLYFLAGS 列挙の定数のいずれかを指定する必要がある。

エラー コード

失敗した場合はエラーが発生し、Err.Number に DSERR_INVALIDPARAM が設定される。

注意

デフォルトの速度は (0,0,0) である。

速度はドップラー効果でのみ使用される。リスナーを移動することはない。リスナーの位置を変更するには DirectSound3DListener8.SetPosition メソッドを使う。

参照

DirectSound3DListener8.GetVelocity、リスナーの位置座標と速度


DirectSound8

DirectSound 再生システムを表す。アプリケーションは DirectSound8 クラスのメソッドを使って、バッファ オブジェクトの作成とオーディオ環境の設定を行う。

DirectX8.DirectSoundCreate 関数を使ってこのクラスのオブジェクトを取得する。

DirectSound8 クラスのメソッドは、次のグループにまとめることができる。

初期化 | SetCooperativeLevel
バッファ作成 | CreatePrimarySoundBuffer
 | CreateSoundBuffer
 | CreateSoundBufferFromFile
 | CreateSoundBufferFromResource
 | DuplicateSoundBuffer
デバイスの能力 | GetCaps
スピーカの構成 | GetSpeakerConfig
 | SetSpeakerConfig


DirectSound8.CreatePrimarySoundBuffer

オーディオ出力のフォーマットの変更や DirectSound3DListener8 オブジェクトの取得に利用できる、プライマリ バッファ オブジェクトを作成する。

object.CreatePrimarySoundBuffer( _
  bufferDesc As DSBUFFERDESC _
) As DirectSoundPrimaryBuffer8

指定項目

object
DirectSound8 オブジェクトを指定する。
bufferDesc
作成するサウンド バッファの記述を指定する DSBUFFERDESC 型。lBufferBytes メンバは 0 でなければならない。また、lFlags は DSBCAPS_PRIMARYBUFFER を保持しなければならない。

戻り値

DirectSoundPrimaryBuffer8 オブジェクトを返す。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかのエラー値が設定される。

DSERR_ALLOCATED
DSERR_BADFORMAT
DSERR_OUTOFMEMORY
DSERR_UNINITIALIZED
DSERR_UNSUPPORTED


DirectSound8.CreateSoundBuffer

サンプリング オーディオをプライマリ バッファにミキシングするための、セカンダリ バッファを作成する。

object.CreateSoundBuffer( _
  bufferDesc As DSBUFFERDESC _
) As DirectSoundSecondaryBuffer8

指定項目

object
DirectSound8 オブジェクトを指定する。
bufferDesc
作成するサウンド バッファの記述を指定する DSBUFFERDESC 型。

戻り値

DirectSoundSecondaryBuffer8 オブジェクトを返す。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかのエラー値が設定される。

DSERR_ALLOCATED
DSERR_BADFORMAT
DSERR_BUFFERTOOSMALL
DSERR_CONTROLUNAVAIL
DSERR_INVALIDCALL
DSERR_INVALIDPARAM
DSERR_OUTOFMEMORY
DSERR_UNINITIALIZED
DSERR_UNSUPPORTED

注意

DirectSound はバッファの内容を初期化しない。アプリケーションでは、バッファの内容が無音であると仮定してはならない。

ハードウェア アクセラレーションを利用できないシステムで DSBCAPS_LOCHARDWARE フラグを使ってバッファを作成しようとすると、メソッドは失敗し、オペレーティング システムに応じて DSERR_CONTROLUNAVAIL または DSERR_INVALIDCALL を返す。

参照

DirectSound8.CreateSoundBufferFromFile、DirectSound8.CreateSoundBufferFromResource、DirectSound8.DuplicateSoundBuffer


DirectSound8.CreateSoundBufferFromFile

サンプリング オーディオをプライマリ バッファにミキシングするためのセカンダリ バッファを作成し、ファイルからバッファにデータをロードする。

object.CreateSoundBufferFromFile( _
  filename As String, _
  bufferDesc As DSBUFFERDESC _
) As DirectSoundSecondaryBuffer8

指定項目

object
DirectSound8 オブジェクトを指定する。
filename
作成したバッファにロードするウェーブ ファイル名。
bufferDesc
作成するサウンド バッファの記述を指定する DSBUFFERDESC 型。メソッドは、データそのものから形式およびサイズを判断するため、fxFormat および lBufferBytes メンバは無視される。

戻り値

DirectSoundSecondaryBuffer8 オブジェクトを返す。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかのエラー値が設定される。

DSERR_ALLOCATED
DSERR_BADFORMAT
DSERR_BUFFERTOOSMALL
DSERR_CONTROLUNAVAIL
DSERR_INVALIDCALL
DSERR_OUTOFMEMORY
DSERR_UNINITIALIZED
DSERR_UNSUPPORTED

注意

ハードウェア アクセラレーションを利用できないシステムで DSBCAPS_LOCHARDWARE フラグを使ってバッファを作成しようとすると、メソッドは失敗し、Windows 95 および Windows 98 では DSERR_CONTROLUNAVAIL を返す。Windows 2000 では DSERR_INVALIDCALL を返す。

参照

DirectSound8.CreateSoundBuffer、DirectSound8.CreateSoundBufferFromResource、DirectSound8.DuplicateSoundBuffer


DirectSound8.CreateSoundBufferFromResource

サンプリング オーディオをプライマリ バッファにミキシングするためのセカンダリ バッファを作成し、リソースからバッファにデータをロードする。サウンド リソースは、WAV または WAVE のどちらかのタイプでなければならない。

object.CreateSoundBufferFromResource( _
  dll As String, _
  resourceName As String, _
  bufferDesc As DSBUFFERDESC _
) As DirectSoundSecondaryBuffer8

指定項目

object
DirectSound8 オブジェクトを指定する。
dll
リソースや、リソースが実行可能ファイルに含まれている場合の vbNullString を含む DLL 名。
resourceName
作成されたサウンド バッファにロードするリソース名。
bufferDesc
作成するサウンド バッファの記述を指定する DSBUFFERDESC 型。メソッドは、データそのものから形式およびサイズを判断するため、fxFormat および lBufferBytes メンバは無視される。

戻り値

DirectSoundSecondaryBuffer8 オブジェクトを返す。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかのエラー値が設定される。

DSERR_ALLOCATED
DSERR_BADFORMAT
DSERR_BUFFERTOOSMALL
DSERR_CONTROLUNAVAIL
DSERR_INVALIDCALL
DSERR_OUTOFMEMORY
DSERR_UNINITIALIZED
DSERR_UNSUPPORTED

注意

ハードウェア アクセラレーションを利用できないシステムで DSBCAPS_LOCHARDWARE フラグを使ってバッファを作成しようとすると、メソッドは失敗し、Windows 95 および Windows 98 では DSERR_CONTROLUNAVAIL を返す。Windows 2000 では DSERR_INVALIDCALL を返す。

参照

DirectSound8.CreateSoundBuffer、DirectSound8.CreateSoundBufferFromFile、DirectSound8.DuplicateSoundBuffer


DirectSound8.DuplicateSoundBuffer

オリジナル バッファのメモリを複製または共有する、新しいセカンダリ バッファを作成する。

object.DuplicateSoundBuffer( _
  original As DirectSoundSecondaryBuffer8 _
) As DirectSoundSecondaryBuffer8

指定項目

object
DirectSound8 オブジェクトを指定する。
original
複製する DirectSoundSecondaryBuffer8 オブジェクト。

戻り値

DirectSoundSecondaryBuffer8 オブジェクトを返す。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかのエラー値が設定される。

DSERR_ALLOCATED
DSERR_INVALIDCALL
DSERR_OUTOFMEMORY
DSERR_UNINITIALIZED

注意

このメソッドは、DSBCAPS_CTRLFX フラグを使って作成したバッファには無効である。

複製直後のバッファは、オリジナル バッファと同じパラメータを持つ。ただし、アプリケーションは各バッファのパラメータを個別に変更でき、各バッファは互いに影響を及ぼすことなく再生と停止を行える。

後に残った参照側オブジェクトが解放されると、バッファ メモリは解放される。

複製バッファが同じメモリを共有する場合もあるが、常にそうであるとは限らない。バッファに格納されたデータに対する変更は、複製に必ずしも反映されない。

参照

DirectSound8.CreateSoundBuffer、DirectSound8.CreateSoundBufferFromFile、DirectSound8.CreateSoundBufferFromResource


DirectSound8.GetCaps

DirectSound8 オブジェクトで表されるハードウェア デバイスの能力を取得する。

object.GetCaps(caps As DSCAPS)

指定項目

object
DirectSound8 オブジェクトを指定する。
caps
サウンド デバイスの能力を受け取る DSCAPS 型。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかのエラー値が設定される。

DSERR_GENERIC
DSERR_UNINITIALIZED

注意

DSCAPS 型に保持されている情報は、ハードウェア ミキシング チャンネルの数、オンボード サウンド メモリの容量など、サウンド デバイスの最大能力と、現在使用可能な能力を記述する。これらの情報を使って性能を調整し、リソースの割り当てを最適化できる。

リソースの共有が前提となっているため、ある分野で最大の能力を利用すると、ほかの分野がその影響を受けることがある。たとえば、ハードウェア スタティック サウンド バッファが 1 つも利用できない場合は、最大数のストリーム サウンド バッファのハードウェア ミキシングが使用可能になる。

参照

DirectX8.DirectSoundCreate


DirectSound8.GetSpeakerConfig

DirectSound8 オブジェクトのスピーカの構成を取得する。

object.GetSpeakerConfig() As CONST_DSSPEAKERFLAGS

指定項目

object
DirectSound8 オブジェクトを指定する。

戻り値

CONST_DSSPEAKERFLAGS 列挙の定数の 1 つまたは複数を保持する Long 値を返す。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかのエラー値が設定される。

DSERR_INVALIDPARAM
DSERR_UNINITIALIZED

注意

スピーカのジオメトリはデフォルトで 0 に設定される。 これは、スピーカのジオメトリが未定義の状態である。ジオメトリは、DirectSound8.SetSpeakerConfig メソッドを使って DSSPEAKER_STEREO フラグにスピーカのジオメトリ フラグの 1 つを渡すことにより、明示的に設定しなければならない。

参照

DirectSound8.SetSpeakerConfig


DirectSound8.SetCooperativeLevel

サウンド デバイスのアプリケーション協調レベルを設定する。

object.SetCooperativeLevel( _
  hwnd As Long, _
  level As CONST_DSSCLFLAGS)

指定項目

object
DirectSound8 オブジェクトを指定する。
hwnd
アプリケーションへのウィンドウ ハンドル。「注意」を参照すること。
level
要求される優先レベル。CONST_DSSCLFLAGS 列挙の定数でなければならない。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかのエラー値が設定される。

DSERR_ALLOCATED
DSERR_INVALIDPARAM
DSERR_UNINITIALIZED
DSERR_UNSUPPORTED

注意

アプリケーションはバッファを再生する前に、このメソッドを呼び出して協調レベルを設定しなければならない。推奨される協調レベルは DSSCL_PRIORITY である。

hwnd パラメータは、最上位のアプリケーション ウィンドウ ハンドルとすべきである。

参照

協調レベル


DirectSound8.SetSpeakerConfig

DirectSound8 オブジェクトのスピーカの構成を指定する。

object.SetSpeakerConfig( _
  speakerConfig As CONST_DSSPEAKERFLAGS)

指定項目

object
DirectSound8 オブジェクトを指定する。
speakerConfig
DirectSound8 オブジェクトのスピーカの構成。CONST_DSSPEAKERFLAGS 列挙の定数の 1 つまたは複数を指定しなければならない。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかのエラー値が設定される。

DSERR_INVALIDPARAM
DSERR_UNINITIALIZED

注意

スピーカのジオメトリはデフォルトで 0 に設定される。これは、スピーカのジオメトリが未定義であることを示す。ジオメトリは、DSSPEAKER_STEREO フラグと組み合わせたスピーカのジオメトリ フラグの 1 つを渡すことにより、明示的に設定しなければならない。

参照

DirectSound8.GetSpeakerConfig、スピーカの構成


DirectSoundCapture8

サウンド キャプチャ デバイスを表す。このクラスのメソッドは、サウンド キャプチャ バッファの作成とそのデバイス能力の問い合わせに使われる。

DirectSoundCapture8 オブジェクトは、DirectX8.DirectSoundCaptureCreate メソッドを使って取得される。

DirectSoundCapture8 クラスのメソッドは、次のグループにまとめることができる。

バッファ作成 | CreateCaptureBuffer
能力 | GetCaps

参照

ウェーブのキャプチャ


DirectSoundCapture8.CreateCaptureBuffer

キャプチャ バッファを作成する。

object.CreateCaptureBuffer( _
  bufferDesc As DSCBUFFERDESC _
) As DirectSoundCaptureBuffer8

指定項目

object
DirectSoundCapture8 オブジェクトを指定する。
bufferDesc
作成されるキャプチャ バッファ用の値を指定する DSCBUFFERDESC 型。

戻り値

DirectSoundCaptureBuffer8 オブジェクトを返す。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかのエラー値が設定される。

DSERR_INVALIDPARAM
DSERR_BADFORMAT
DSERR_GENERIC
DSERR_NODRIVER
DSERR_OUTOFMEMORY
DSERR_UNINITIALIZED

注意

Microsoft® Windows® 95、Windows® 98、および Windows® 2000 では、各キャプチャ デバイスは単一のバッファをサポートする。


DirectSoundCapture8.GetCaps

キャプチャ デバイスの能力を取得する。

object.GetCaps(caps As DSCCAPS)

指定項目

object
DirectSoundCapture8 オブジェクトを指定する。
caps
キャプチャ デバイスの能力を受け取る DSCCAPS 型。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかのエラー値が設定される。

DSERR_INVALIDPARAM
DSERR_UNSUPPORTED
DSERR_NODRIVER
DSERR_OUTOFMEMORY
DSERR_UNINITIALIZED


DirectSoundCaptureBuffer8

サウンドのキャプチャに使われるバッファを表す。

DirectSoundCapture8.CreateCaptureBuffer メソッドを呼び出して DirectSoundCaptureBuffer8 クラスのオブジェクトを取得する。

DirectSoundCaptureBuffer8 クラスのメソッドは、次のグループにまとめることができる。

情報 | GetCaps
 | GetCurrentPosition
 | GetFormat
 | GetStatus
バッファ データ | ReadBuffer
 | WriteBuffer
通知 | SetNotificationPositions
キャプチャ管理 | Start
 | Stop

参照

ウェーブのキャプチャ


DirectSoundCaptureBuffer8.GetCaps

バッファの能力を返す。

object.GetCaps(caps As DSCBCAPS)

指定項目

object
DirectSoundCaptureBuffer8 オブジェクトを指定する。
caps
キャプチャ バッファの能力を受け取る DSCBCAPS 型。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかのエラー値が設定される。

DSERR_INVALIDPARAM
DSERR_UNSUPPORTED
DSERR_OUTOFMEMORY


DirectSoundCaptureBuffer8.GetCurrentPosition

キャプチャおよび読み込みカーソルを取得する。

object.GetCurrentPosition(cursors As DSCURSORS)

指定項目

object
DirectSoundCaptureBuffer8 オブジェクトを指定する。
cursors
キャプチャ カーソルおよび読み込みカーソルを受け取る DSCURSORS 型。各値はバッファの先頭からのオフセットであり、単位はバイトである。「注意」を参照すること。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかのエラー値が設定される。

DSERR_INVALIDPARAM
DSERR_NODRIVER
DSERR_OUTOFMEMORY

注意

キャプチャ カーソルの DSCURSORS.lPlay は、データがキャプチャされる位置を示す。読み込みカーソルの DSCURSORS.lWrite は、キャプチャ カーソルの後ろにあり、この位置まではデータを安全に読み込みできる。バッファリングのため、lWrite より後ろで lPlay より前のデータは (キャプチャ位置を含む)、必ずしも有効なデータとは限らない。

参照

キャプチャ バッファの情報


DirectSoundCaptureBuffer8.GetFormat

キャプチャ バッファのフォーマットを取得する。

object.GetFormat(waveformat As WAVEFORMATEX)

指定項目

object
DirectSoundCaptureBuffer8 オブジェクトを指定する。
waveformat
キャプチャ バッファ フォーマットの記述を受け取る WAVEFORMATEX 型。

エラー コード

失敗した場合はエラーが発生し、Err.Number に DSERR_INVALIDPARAM が設定される。


DirectSoundCaptureBuffer8.GetStatus

キャプチャ バッファの現在のステータスを取得する。

object.GetStatus() As CONST_DSCBSTATUSFLAGS

指定項目

object
DirectSoundCaptureBuffer8 オブジェクトを指定する。

戻り値

CONST_DSCBSTATUSFLAGS 列挙の定数の 1 つまたは複数を保持する Long 値を返す。

エラー コード

失敗した場合はエラーが発生し、Err.Number に DSERR_INVALIDPARAM が設定される。


DirectSoundCaptureBuffer8.ReadBuffer

サウンド バッファのセグメントを読み込み、アプリケーション バッファにそのデータを格納する。

object.ReadBuffer( _
  start As Long, _
  size As Long, _
  buffer As Any, _
  flags As CONST_DSCBLOCKFLAGS)

指定項目

object
DirectSoundCaptureBuffer8 オブジェクトを指定する。
start
バッファの先頭から読み込み開始位置までのオフセット (バイト単位)。
size
読み込むバッファ部分のサイズ (バイト単位)。サウンド バッファは概念的には循環バッファであるため、この値はバッファの start から最後までの間のバイト数よりも大きい値になる。定数 DSCBLOCK_ENTIREBUFFER を引数 flags に設定すると、このパラメータは無視される。
buffer
データの読み込みを保持する変数。通常、これはバイトの配列であり、配列の先頭要素を渡す。
flags
CONST_DSCBLOCKFLAGS 列挙の定数のいずれかを指定する。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかのエラー コードが設定される。

DSERR_BUFFERLOST
DSERR_INVALIDCALL
DSERR_INVALIDPARAM
DSERR_PRIOLEVELNEEDED

参照

DirectSoundCaptureBuffer8.GetCurrentPosition


DirectSoundCaptureBuffer8.SetNotificationPositions

通知イベントがシグナル送信されるバッファ内の位置を設定する。読み込みカーソルが通知位置に到達すると、イベントがシグナル送信される。

object.SetNotificationPositions( _
  nElements As Long, _
  psa() As DSBPOSITIONNOTIFY)

指定項目

object
DirectSoundCaptureBuffer8 オブジェクトを指定する。
nElements
psa 配列における要素数。
psa
通知位置および関連するイベントを指定する DSBPOSITIONNOTIFY 型の配列。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかのエラー コードが設定される。

DSERR_BUFFERLOST
DSERR_INVALIDCALL
DSERR_INVALIDPARAM
DSERR_PRIOLEVELNEEDED

参照

DirectSoundCaptureBuffer8.GetCurrentPosition


DirectSoundCaptureBuffer8.Start

データのバッファへのキャプチャを開始する。キャプチャ バッファが既にキャプチャ状態にある場合には、このメソッドは何もしない。

object.Start(flags As CONST_DSCBSTARTFLAGS)

指定項目

object
DirectSoundCaptureBuffer8 オブジェクトを指定する。
flags
サウンド データをキャプチャリングするときのキャプチャ バッファの動作を指定するフラグ。CONST_DSCBSTARTFLAGS 列挙の定数のいずれかを指定する。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかのエラー値が設定される。

DSERR_INVALIDPARAM
DSERR_NODRIVER
DSERR_OUTOFMEMORY


DirectSoundCaptureBuffer8.Stop

データのキャプチャを停止する。キャプチャ バッファが既に停止している場合は、このメソッドは何もしない。

object.Stop()

指定項目

object
DirectSoundCaptureBuffer8 オブジェクトを指定する。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかのエラー値が設定される。

DSERR_NODRIVER
DSERR_OUTOFMEMORY


DirectSoundCaptureBuffer8.WriteBuffer

キャプチャ バッファにデータを書き込む。データは DirectSoundCaptureBuffer8.Start メソッドに応じて書き込まれるため、ほとんどのアプリケーションはこのメソッドを使用しない。

object.WriteBuffer( _
  start As Long, _
  size As Long, _
  buffer As Any, _
  flags As CONST_DSCBLOCKFLAGS)

指定項目

object
DirectSoundCaptureBuffer8 オブジェクトを指定する。
start
バッファの先頭から書き込みを開始する位置までのオフセット (バイト単位)。
size
読み込むバッファ部分のサイズ (バイト単位)。サウンド バッファは概念的には循環バッファであるため、この値はバッファの start から最後までの間のバイト数よりも大きい値になる。DSCBLOCK_ENTIREBUFFER を flags パラメータに設定すると、このパラメータは無視される。
buffer
キャプチャ バッファに書き込むデータを保持する変数。通常、これはバイトの配列であり、配列の先頭要素を渡す。
flags
CONST_DSCBLOCKFLAGS 列挙の定数のいずれかを指定する。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかのエラー コードが設定される。

DSERR_BUFFERLOST
DSERR_INVALIDCALL
DSERR_INVALIDPARAM
DSERR_PRIOLEVELNEEDED

参照

DirectSoundCaptureBuffer8.GetCurrentPosition


DirectSoundEnum8

DirectSoundEnum8 クラスのオブジェクトは、DirectSound で利用可能なデバイスのコレクションを表す。オブジェクトは、DirectX8.GetDSEnum または DirectX8.GetDSCaptureEnum メソッドを使って取得する。

このクラスには次のメソッドがある。

情報 | GetCount
 | GetDescription
 | GetGuid
 | GetName

参照

サウンド デバイスの列挙、キャプチャ デバイスの列挙


DirectSoundEnum8.GetCount

列挙内のデバイス数を取得する。

object.GetCount() As Long

指定項目

object
DirectSoundEnum8 オブジェクトを指定する。

戻り値

列挙内のエントリ数を返す。

エラー コード

失敗した場合はエラーが発生し、Err.Number が設定される。


DirectSoundEnum8.GetDescription

列挙内のデバイスの一般的な名前を取得する。

object.GetDescription(index As Long) As String

指定項目

object
DirectSoundEnum8 オブジェクトを指定する。
index
列挙内のデバイスのインデックス。

戻り値

ドライバから提供されるデバイスの説明を返す。

エラー コード

失敗した場合はエラーが発生し、Err.Number が設定される。


DirectSoundEnum8.GetGuid

列挙内のデバイスの一意な識別子を取得する。

object.GetGuid(index As Long) As String

指定項目

object
DirectSoundEnum8 オブジェクトを指定する。
index
列挙内のデバイスのインデックス。

戻り値

成功すればデバイスの GUID を文字列形式で返す。

エラー コード

失敗した場合はエラーが発生し、Err.Number が設定される。

参照

GUID の使い方


DirectSoundEnum8.GetName

列挙内のデバイス ドライバの名前を返す。

object.GetName(index As Long) As String
object
DirectSoundEnum8 オブジェクトを指定する。
index
列挙内のデバイスのインデックス。

戻り値

デバイス ドライバの名前を返す。これは一般的なデバイス名ではなく、DirectSoundEnum8.GetDescription によって返される。

エラー コード

失敗した場合はエラーが発生し、Err.Number に DSERR_INVALIDPARAM が設定される。


DirectSoundFXChorus8

コーラスをサポートするバッファで、エフェクト パラメータを設定および取得するために使用する。

このクラスのオブジェクトは、エフェクトをサポートするバッファで DirectSoundSecondaryBuffer8.GetObjectInPath を呼び出して取得する。

DirectSoundFXChorus8 クラスには、次のメソッドがある。

パラメータ | GetAllParameters
 | SetAllParameters

参照

DirectSoundSecondaryBuffer8.SetFX


DirectSoundFXChorus8.GetAllParameters

バッファのコーラス パラメータを取得する。

object.GetAllParameters() As DSFXCHORUS

指定項目

object
DirectSoundFXChorus8 オブジェクトを指定する。

戻り値

エフェクトのパラメータを保持する DSFXCHORUS 型を返す。

エラー コード

失敗した場合はエラーが発生する。Err.Number に設定される値には、DSERR_INVALIDPARAM が含まれる。


DirectSoundFXChorus8.SetAllParameters

バッファの振幅変調パラメータを設定する。

object.SetAllParameters(params As DSFXCHORUS)

指定項目

object
DirectSoundFXChorus8 オブジェクトを指定する。
params
エフェクトのパラメータを指定する DSFXCHORUS 型。

エラー コード

失敗した場合はエラーが発生する。Err.Number に設定される値には、DSERR_INVALIDPARAM が含まれる。


DirectSoundFXCompressor8

コンプレッサ エフェクトをサポートするバッファで、エフェクト パラメータを設定および取得するために使用する。

このクラスのオブジェクトは、エフェクトをサポートするバッファで DirectSoundSecondaryBuffer8.GetObjectInPath を呼び出して取得する。

DirectSoundFXCompressor8 クラスには、次のメソッドがある。

パラメータ | GetAllParameters
 | SetAllParameters

参照

DirectSoundSecondaryBuffer8.SetFX、コンプレッション


DirectSoundFXCompressor8.GetAllParameters

バッファのコンプレッサ パラメータを取得する。

object.GetAllParameters() As DSFXCOMPRESSOR

指定項目

object
DirectSoundFXCompressor8 オブジェクトを指定する。

戻り値

エフェクトのパラメータを保持する DSFXCOMPRESSOR 型を返す。

エラー コード

失敗した場合はエラーが発生する。Err.Number に設定される値には、DSERR_INVALIDPARAM が含まれる。


DirectSoundFXCompressor8.SetAllParameters

バッファのコンプレッサ パラメータを設定する。

object.SetAllParameters(params As DSFXCOMPRESSOR)

指定項目

object
DirectSoundFXCompressor8 オブジェクトを指定する。
params
エフェクトのパラメータを指定する DSFXCOMPRESSOR 型。

エラー コード

失敗した場合はエラーが発生する。Err.Number に設定される値には、DSERR_INVALIDPARAM が含まれる。


DirectSoundFXDistortion8

ディストーション エフェクトをサポートするバッファで、エフェクト パラメータを設定および取得するために使用する。

このクラスのオブジェクトは、エフェクトをサポートするバッファで DirectSoundSecondaryBuffer8.GetObjectInPath を呼び出して取得する。

DirectSoundFXDistortion8 クラスには、次のメソッドがある。

パラメータ | GetAllParameters
 | SetAllParameters

参照

DirectSoundSecondaryBuffer8.SetFX


DirectSoundFXDistortion8.GetAllParameters

バッファのディストーション パラメータを取得する。

object.GetAllParameters() As DSFXDISTORTION

指定項目

object
DirectSoundFXDistortion8 オブジェクトを指定する。

戻り値

エフェクトのパラメータを保持する DSFXDISTORTION 型を返す。

エラー コード

失敗した場合はエラーが発生する。Err.Number に設定される値には、DSERR_INVALIDPARAM が含まれる。


DirectSoundFXDistortion8.SetAllParameters

バッファのディストーション パラメータを設定する。

object.SetAllParameters(params As DSFXDISTORTION)

指定項目

object
DirectSoundFXDistortion8 オブジェクトを指定する。
params
エフェクトのパラメータを指定する DSFXDISTORTION 型。

エラー コード

失敗した場合はエラーが発生する。Err.Number に設定される値には、DSERR_INVALIDPARAM が含まれる。


DirectSoundFXEcho8

エコー エフェクトをサポートするバッファで、エフェクト パラメータを設定および取得するために使用する。

このクラスのオブジェクトは、エフェクトをサポートするバッファで DirectSoundSecondaryBuffer8.GetObjectInPath を呼び出して取得する。

DirectSoundFXEcho8 クラスには、次のメソッドがある。

パラメータ | GetAllParameters
 | SetAllParameters

参照

DirectSoundSecondaryBuffer8.SetFX


DirectSoundFXEcho8.GetAllParameters

バッファのエコー パラメータを取得する。

object.GetAllParameters() As DSFXECHO

指定項目

object
DirectSoundFXEcho8 オブジェクトを指定する。

戻り値

エフェクトのパラメータを保持する DSFXECHO 型を返す。

エラー コード

失敗した場合はエラーが発生する。Err.Number に設定される値には、DSERR_INVALIDPARAM が含まれる。


DirectSoundFXEcho8.SetAllParameters

バッファのエコー パラメータを設定する。

object.SetAllParameters(params As DSFXECHO)

指定項目

object
DirectSoundFXEcho8 オブジェクトを指定する。
params
エフェクトのパラメータを指定する DSFXECHO 型。

エラー コード

失敗した場合はエラーが発生する。Err.Number に設定される値には、DSERR_INVALIDPARAM が含まれる。


DirectSoundFXFlanger8

フランジャ エフェクトをサポートするバッファで、エフェクト パラメータを設定および取得するために使用する。

このクラスのオブジェクトは、エフェクトをサポートするバッファで DirectSoundSecondaryBuffer8.GetObjectInPath を呼び出して取得する。

DirectSoundFXFlanger8 クラスには、次のメソッドがある。

パラメータ | GetAllParameters
 | SetAllParameters

参照

DirectSoundSecondaryBuffer8.SetFX


DirectSoundFXFlanger8.GetAllParameters

バッファのフランジャ パラメータを取得する。

object.GetAllParameters() As DSFXFLANGER

指定項目

object
DirectSoundFXFlanger8 オブジェクトを指定する。

戻り値

エフェクトのパラメータを保持する DSFXFLANGER 型を返す。

エラー コード

失敗した場合はエラーが発生する。Err.Number に設定される値には、DSERR_INVALIDPARAM が含まれる。


DirectSoundFXFlanger8.SetAllParameters

バッファのフランジャ パラメータを設定する。

object.SetAllParameters(params As DSFXFLANGER)

指定項目

object
DirectSoundFXFlanger8 オブジェクトを指定する。
params
エフェクトのパラメータを指定する DSFXFLANGER 型。

エラー コード

失敗した場合はエラーが発生する。Err.Number に設定される値には、DSERR_INVALIDPARAM が含まれる。


DirectSoundFXGargle8

振幅変調をサポートするバッファで、エフェクト パラメータを設定および取得するために使用する。

このクラスのオブジェクトは、エフェクトをサポートするバッファで DirectSoundSecondaryBuffer8.GetObjectInPath を呼び出して取得する。

DirectSoundFXGargle8 クラスには、次のメソッドがある。

パラメータ | GetAllParameters
 | SetAllParameters

参照

DirectSoundSecondaryBuffer8.SetFX


DirectSoundFXGargle8.GetAllParameters

バッファの振幅変調パラメータを取得する。

object.GetAllParameters() As DSFXGARGLE

指定項目

object
DirectSoundFXGargle8 オブジェクトを指定する。

戻り値

エフェクトのパラメータを保持する DSFXGARGLE 型を返す。

エラー コード

失敗した場合はエラーが発生する。Err.Number に設定される値には、DSERR_INVALIDPARAM が含まれる。


DirectSoundFXGargle8.SetAllParameters

バッファの振幅変調パラメータを設定する。

object.SetAllParameters(params As DSFXGARGLE)

指定項目

object
DirectSoundFXGargle8 オブジェクトを指定する。
params
エフェクトのパラメータを指定する DSFXGARGLE 型。

エラー コード

失敗した場合はエラーが発生する。Err.Number に設定される値には、DSERR_INVALIDPARAM が含まれる。


DirectSoundFXI3DL2Reverb8

I3DL2 (Interactive 3D Audio Level 2) リバーブ エフェクトをサポートするバッファで、エフェクト パラメータを設定および取得するために使用する。

このクラスのオブジェクトは、エフェクトをサポートするバッファで DirectSoundSecondaryBuffer8.GetObjectInPath を呼び出して取得する。

DirectSoundFXI3DL2Reverb8 クラスには、次のメソッドがある。

パラメータ | GetAllParameters
 | SetAllParameters
プリセット値 | GetPreset
 | SetPreset
クオリティ | GetQuality
 | SetQuality

参照

DirectSoundSecondaryBuffer8.SetFX


DirectSoundFXI3DL2Reverb8.GetAllParameters

バッファの I3DL2 (Interactive 3D Audio Level 2) リバーブ パラメータを取得する。

object.GetAllParameters() As DSFXI3DL2REVERB

指定項目

object
DirectSoundFXI3DL2Reverb8 オブジェクトを指定する。

戻り値

エフェクトのパラメータを保持する DSFXI3DL2REVERB 型を返す。

エラー コード

失敗した場合はエラーが発生する。Err.Number に設定される値には、DSERR_INVALIDPARAM が含まれる。


DirectSoundFXI3DL2Reverb8.GetPreset

バッファの標準リバーブ パラメータの識別子を取得する。

object.GetPreset() As Long

指定項目

object
DirectSoundFXI3DL2Reverb8 オブジェクトを指定する。

戻り値

CONST_DSFX_I3DL2_ENVIRONMENT_PRESETS 列挙から、あらかじめ設定された識別子を返す。あらかじめ設定される値に関連するデフォルトのパラメータについては、Dsound.h を参照すること。

エラー コード

失敗した場合はエラーが発生する。Err.Number に設定される値は、次のとおりである。

DSERR_INVALIDPARAM
DSERR_INVALIDCALL


DirectSoundFXI3DL2Reverb8.GetQuality

環境リバーブ エフェクトのクオリティを取得する。

object.GetQuality() As Long

指定項目

object
DirectSoundFXI3DL2Reverb8 オブジェクトを指定する。

戻り値

エフェクトのクオリティを返す。

エラー コード

失敗した場合はエラーが発生する。Err.Number に設定される値には、DSERR_INVALIDPARAM が含まれる。

参照

DirectSoundFXI3DL2Reverb8.SetQuality


DirectSoundFXI3DL2Reverb8.SetAllParameters

バッファの I3DL2 (Interactive 3D Audio Level 2) リバーブ パラメータを設定する。

object.SetAllParameters(params As DSFXI3DL2REVERB)

指定項目

object
DirectSoundFXI3DL2Reverb8 オブジェクトを指定する。
params
エフェクトのパラメータを指定する DSFXI3DL2REVERB 型。

エラー コード

失敗した場合はエラーが発生する。Err.Number に設定される値には、DSERR_INVALIDPARAM が含まれる。


DirectSoundFXI3DL2Reverb8.SetPreset

バッファの標準リバーブ パラメータを設定する。

object.SetPreset(lPreset As Long)

指定項目

object
DirectSoundFXI3DL2Reverb8 オブジェクトを指定する。
lPreset
デフォルト パラメータのセットを指定する CONST_DSFX_I3DL2_ENVIRONMENT_PRESETS 列挙の定数。各定数に関連付けられたパラメータについては、dsound.h を参照すること。

エラー コード

失敗した場合はエラーが発生する。Err.Number に設定される値には、DSERR_INVALIDPARAM が含まれる。


DirectSoundFXI3DL2Reverb8.SetQuality

環境リバーブ エフェクトのクオリティを設定する。高い値を指定すると、クオリティは良くなるが、処理にかかる時間が長くなる。

object.SetQuality( _
  lQuality As CONST_DSFX_I3DL2REVERB_QUALITY)

指定項目

object
DirectSoundFXI3DL2Reverb8 オブジェクトを指定する。
lQuality
エフェクトのクオリティを指定する値。最小値および最大値は、CONST_DSFX_I3DL2REVERB_QUALITY 列挙で定義されている。デフォルト値は 2 である。

戻り値

エフェクトのクオリティを返す。

エラー コード

失敗した場合はエラーが発生する。Err.Number に設定される値には、DSERR_INVALIDPARAM が含まれる。

参照

DirectSoundFXI3DL2Reverb8.GetQuality


DirectSoundFXParamEq8

パラメトリック イコライザ エフェクトをサポートするバッファで、エフェクト パラメータを設定および取得するために使用する。

このクラスのオブジェクトは、エフェクトをサポートするバッファで DirectSoundSecondaryBuffer8.GetObjectInPath を呼び出して取得する。

DirectSoundFXParameq8 クラスには、次のメソッドがある。

パラメータ | GetAllParameters
 | SetAllParameters

参照

DirectSoundSecondaryBuffer8.SetFX


DirectSoundFXParamEq8.GetAllParameters

バッファのパラメトリック イコライザ パラメータを取得する。

object.GetAllParameters() As DSFXPARAMEQ

指定項目

object
DirectSoundFXParamEq8 オブジェクトを指定する。

戻り値

エフェクトのパラメータを保持する DSFXPARAMEQ 型を返す。

エラー コード

失敗した場合はエラーが発生する。Err.Number に設定される値には、DSERR_INVALIDPARAM が含まれる。


DirectSoundFXParamEq8.SetAllParameters

バッファのパラメトリック イコライザ パラメータを設定する。

object.SetAllParameters(params As DSFXPARAMEQ)

指定項目

object
DirectSoundFXParamEq8 オブジェクトを指定する。
params
エフェクトのパラメータを指定する DSFXPARAMEQ 型。

エラー コード

失敗した場合はエラーが発生する。Err.Number に設定される値には、DSERR_INVALIDPARAM が含まれる。


DirectSoundFXWavesReverb8

ウェーブ リバーブをサポートするバッファで、エフェクト パラメータを設定および取得するために使用する。

このクラスのオブジェクトは、エフェクトをサポートするバッファで DirectSoundSecondaryBuffer8.GetObjectInPath を呼び出して取得する。

DirectSoundFXWavesReverb8 クラスには、次のメソッドがある。

パラメータ | GetAllParameters
 | SetAllParameters

注意

ウェーブ リバーブ DMO は、Microsoft にライセンスされている Waves MaxxVerb テクノロジに基づいている。

参照

DirectSoundSecondaryBuffer8.SetFX


DirectSoundFXWavesReverb8.GetAllParameters

バッファのウェーブ リバーブ パラメータを取得する。

object.GetAllParameters() As DSFXWAVESREVERB

指定項目

object
DirectSoundFXWavesReverb8 オブジェクトを指定する。

戻り値

エフェクトのパラメータを保持する DSFXWAVESREVERB 型を返す。

エラー コード

失敗した場合はエラーが発生する。Err.Number に設定される値には、DSERR_INVALIDPARAM が含まれる。


DirectSoundFXWavesReverb8.SetAllParameters

バッファのウェーブ リバーブ パラメータを設定する。

object.SetAllParameters(params As DSFXWAVESREVERB)

指定項目

object
DirectSoundFXWavesReverb8 オブジェクトを指定する。
params
エフェクトのパラメータを指定する DSFXWAVESREVERB 型。

エラー コード

失敗した場合はエラーが発生する。Err.Number に設定される値には、DSERR_INVALIDPARAM が含まれる。


DirectSoundPrimaryBuffer8

プライマリ サウンド バッファを表す。

DirectSoundPrimaryBuffer8 クラスのオブジェクトは、DirectSound8.CreatePrimarySoundBuffer メソッドを使って取得できる。プライマリ バッファ オブジェクトは一般的に、出力フォーマットの設定、およびグローバル サウンド パラメータを制御する 3D リスナーの取得に使用される。特殊なアプリケーションでは、プライマリ バッファへのデータのミキシングを処理できるが、この処理は通常、セカンダリ バッファを再生するときに DirectSound によって処理される。

このクラスのメソッドは、次のグループにまとめることができる。

データ ストリーム | Play
 | ReadBuffer
 | Stop
 | WriteBuffer
パラメータ | GetCaps
 | GetCurrentPosition
 | GetDirectSound3DListener
 | GetFormat
 | GetPan
 | GetStatus
 | GetVolume
 | SetFormat
 | SetPan
 | SetVolume
その他 | Restore

参照

DirectSoundSecondaryBuffer8


DirectSoundPrimaryBuffer8.GetCaps

バッファの能力を取得する。

object.GetCaps(caps As DSBCAPS)

指定項目

object
DirectSoundPrimaryBuffer8 オブジェクトを指定する。
caps
バッファの能力を受け取る DSBCAPS 型。

エラー コード

失敗した場合はエラーが発生し、Err.Number に DSERR_INVALIDPARAM が設定される。


DirectSoundPrimaryBuffer8.GetCurrentPosition

再生カーソルと書き込みカーソルの位置を取得する。

object.GetCurrentPosition(cursors As DSCURSORS)

指定項目

object
DirectSoundPrimaryBuffer8 オブジェクトを指定する。
cursors
再生カーソルと書き込みカーソルのオフセット (バイト単位) を受け取る DSCURSORS 型。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

DSERR_INVALIDPARAM
DSERR_PRIOLEVELNEEDED

注意

書き込みカーソルは、データ書き込みを安全に行える、バッファの先頭位置である。再生カーソルより後ろ、および書き込みカーソルの前方にあるバッファには、データを書き込むべきではない。詳細については、「再生カーソルと書き込みカーソル」を参照すること。


DirectSoundPrimaryBuffer8.GetDirectSound3DListener

リスナー オブジェクトを返す。このオブジェクトは、サウンドを聞いている人物を表す。リスナー オブジェクトは、グローバル サウンド パラメータの設定に使用できる。

object.GetDirectSound3DListener() As DirectSound3DListener8

指定項目

object
DirectSoundPrimaryBuffer8 オブジェクトを指定する。

戻り値

DirectSound3DListener8 オブジェクトを返す。

エラー コード

失敗した場合はエラーが発生し、Err.Number が設定される。

注意

このメソッドは、プライマリ バッファが DSBCAPS_CTRL3D フラグで作成された場合にだけ成功する。


DirectSoundPrimaryBuffer8.GetFormat

バッファのウェーブ フォーマットの記述を取得する。

object.GetFormat(format As WAVEFORMATEX)

指定項目

object
DirectSoundPrimaryBuffer8 オブジェクトを指定する。
format
バッファのウェーブ フォーマットの記述を受け取る WAVEFORMATEX 型。

エラー コード

失敗した場合はエラーが発生し、Err.Number に DSERR_INVALIDPARAM が設定される。

参照

DirectSoundPrimaryBuffer8.SetFormat


DirectSoundPrimaryBuffer8.GetPan

左右のオーディオ チャンネルの相対ボリュームを示す変数を取得する。

object.GetPan() As Long

指定項目

object
DirectSoundPrimaryBuffer8 オブジェクトを指定する。

戻り値

左右のスピーカの相対ミキシング率を返す。「注意」を参照すること。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかのエラー コードが設定される。

DSERR_CONTROLUNAVAIL
DSERR_INVALIDPARAM
DSERR_PRIOLEVELNEEDED

注意

戻り値は、DSBPAN_LEFT (-10,000) から DSBPAN_RIGHT (10,000) の範囲で、100 分の 1 デシベル (dB) 単位で測定される。値 DSBPAN_LEFT は右チャンネルが 100 dB 減衰していることを意味する。値 DSBPAN_RIGHT は左チャンネルが 100 dB 減衰していることを意味する。中立値 DSBPAN_CENTER (0) は、両方のチャンネルが最大ボリュームであることを意味する (どちらも 0 dB の減衰である)。

DSBPAN_CENTER 以外の値はいずれも、一方のチャンネルが最大ボリュームでもう一方のチャンネルが減衰していることを意味する。たとえば、値 -2173 は、左チャンネルは最大ボリュームで、右チャンネルは 21.73 dB 減衰していることを意味する。同様に、パンの値が 870 のとき、左チャンネルは 8.7 dB 減衰しており、右チャンネルは最大ボリュームであることを意味する。

パン コントロールの効果は、ボリューム コントロールに累積される。

参照

DirectSoundPrimaryBuffer8.GetVolume、DirectSoundPrimaryBuffer8.SetPan、DirectSoundPrimaryBuffer8.SetVolume


DirectSoundPrimaryBuffer8.GetStatus

サウンド バッファのステータスを取得する。

object.GetStatus() As CONST_DSBSTATUSFLAGS

指定項目

object
DirectSoundPrimaryBuffer8 オブジェクトを指定する。

戻り値

サウンド バッファのステータスを返す。ステータスはバッファが失われているか再生中のどちらでもないことを示す 0、または CONST_DSBSTATUSFLAGS 列挙の定数の組み合わせである。

エラー コード

失敗した場合はエラーが発生し、Err.Number が設定される。


DirectSoundPrimaryBuffer8.GetVolume

サウンド バッファのボリュームを取得する。

object.GetVolume() As Long

指定項目

object
DirectSoundPrimaryBuffer8 オブジェクトを指定する。

戻り値

バッファのボリュームを返す。「注意」を参照すること。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかのエラー コードが設定される。

DSERR_CONTROLUNAVAIL
DSERR_INVALIDPARAM
DSERR_PRIOLEVELNEEDED

注意

ボリュームは減衰の 100 分の 1 デシベル (dB) 単位で指定される。設定可能な値は DSBVOLUME_MAX (減衰なし) と DSBVOLUME_MIN (無音) の間である。これらの値は、それぞれ 0、-10,000 と定義されている。値 DSBVOLUME_MAX は、サウンド本来の未調整のボリュームを表す。値 DSBVOLUME_MIN は、オーディオのボリュームが 100 dB 減衰していることを表すが、これは実際的には無音を意味する。

参照

DirectSoundPrimaryBuffer8.SetVolume、DirectSoundPrimaryBuffer8.GetPan


DirectSoundPrimaryBuffer8.Play

プライマリ バッファを再生する。

object.Play(flags As CONST_DSBPLAYFLAGS)

指定項目

object
DirectSoundPrimaryBuffer8 オブジェクトを指定する。
flags
DSBPLAY_LOOPING でなければならない。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかのエラー コードが設定される。

DSERR_BUFFERLOST
DSERR_INVALIDCALL
DSERR_INVALIDPARAM
DSERR_PRIOLEVELNEEDED

参照

DirectSoundPrimaryBuffer8.Stop


DirectSoundPrimaryBuffer8.ReadBuffer

バッファのセグメントを読み込み、アプリケーション バッファにそのデータを格納する。プライマリ バッファは DirectSoundPrimaryBuffer8.Play メソッドに応じてデータをサウンド デバイスのストリームに入れるため、ほとんどのアプリケーションはこのメソッドを使用しない。

object.ReadBuffer( _
  start As Long, _
  size As Long, _
  buffer As Any, _
  flags As CONST_DSBLOCKFLAGS)

指定項目

object
DirectSoundPrimaryBuffer8 オブジェクトを指定する。
start
バッファの先頭から読み込み開始位置までのオフセット (バイト単位)。flags パラメータに DSBLOCK_FROMWRITECURSOR が指定された場合、このパラメータは無視される。
size
読み込むバッファ部分のサイズ (バイト単位)。サウンド バッファは概念的には循環バッファであるため、この値はバッファの start から最後までの間のバイト数よりも大きい値になる。flags パラメータに DSBLOCK_ENTIREBUFFER が指定された場合、このパラメータは無視される。
buffer
データの読み込みを保持する変数。通常、これはバイトの配列であり、配列の先頭要素を渡す。
flags
CONST_DSBLOCKFLAGS 列挙の定数の 1 つ。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかのエラー コードが設定される。

DSERR_BUFFERLOST
DSERR_INVALIDCALL
DSERR_INVALIDPARAM
DSERR_PRIOLEVELNEEDED

参照

DirectSoundPrimaryBuffer8.WriteBuffer


DirectSoundPrimaryBuffer8.Restore

失われたサウンド バッファへのメモリ割り当てを復元する。

object.Restore()

指定項目

object
DirectSoundPrimaryBuffer8 オブジェクトを指定する。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかのエラー コードが設定される。

DSERR_BUFFERLOST
DSERR_INVALIDCALL
DSERR_PRIOLEVELNEEDED

注意

DirectSound がバッファ メモリを復元した後、有効なサウンド データでバッファを書き込み直す必要がある。DirectSound はメモリ自体を復元するが、メモリの内容は復元できない。

アプリケーションはバッファを指定して DirectSoundSecondaryBuffer8.Play メソッドを呼び出すと、そのバッファが失われている場合に通知を受けられる。バッファが失われている場合、このメソッドは DSERR_BUFFERLOST エラーを起こす。DirectSoundSecondaryBuffer8.GetStatus メソッドを使って、サウンド バッファのステータスの取得と DSBSTATUS_BUFFERLOST フラグのテストを行うこともできる。

参照

DirectSoundPrimaryBuffer8.GetStatus


DirectSoundPrimaryBuffer8.SetFormat

バッファのフォーマットを設定する。このアプリケーションに入力フォーカスが置かれるたびに、DirectSound はプライマリ バッファを指定されたフォーマットに設定する。

object.SetFormat(format As WAVEFORMATEX)

指定項目

object
DirectSoundPrimaryBuffer8 オブジェクトを指定する。
format
プライマリ サウンド バッファの新しいフォーマットを指定する WAVEFORMATEX 型。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかのエラー値が設定される。

DSERR_BADFORMAT
DSERR_INVALIDCALL
DSERR_INVALIDPARAM
DSERR_OUTOFMEMORY
DSERR_PRIOLEVELNEEDED

注意

プライマリ バッファのフォーマットは、セカンダリ バッファを作成する前に設定しておく。

アプリケーションに DSSCL_NORMAL 協調レベルが設定されていると、このメソッドは失敗する。

アプリケーションが DSSCL_WRITEPRIMARY 協調レベルで DirectSound を使用している場合、SetFormat を呼び出す前にバッファを停止しなければならない。フォーマットがサポートされていない場合、メソッドは失敗する。

協調レベルが DSSCL_PRIORITY である場合、DirectSound はプライマリ バッファを停止し、フォーマットを変更して、バッファを再開する。要求されたフォーマットをハードウェアがサポートしていない場合でも、メソッドは成功する。DirectSound は、要求に最も近いフォーマットにバッファを設定する。このような状況が発生しているかどうかを判断するには、アプリケーションはプライマリ バッファに対して DirectSoundPrimaryBuffer8.GetFormat メソッドを呼び出し、その結果を、SetFormat メソッドで要求したフォーマットと比較する。

このメソッドはセカンダリ サウンド バッファでは利用できない。新しいフォーマットが要求された場合、アプリケーションは新しい DirectSoundBuffer オブジェクトを作成しなければならない。

参照

バッファ フォーマットのマッチング


DirectSoundPrimaryBuffer8.SetPan

左右のチャンネルの相対ボリュームを指定する。

object.SetPan(pan As Long)

指定項目

object
DirectSoundPrimaryBuffer8 オブジェクトを指定する。
pan
左右のチャンネルの相対ボリューム。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかのエラー値が設定される。

DSERR_CONTROLUNAVAIL
DSERR_GENERIC
DSERR_INVALIDPARAM
DSERR_PRIOLEVELNEEDED

注意

戻り値は、DSBPAN_LEFT (-10,000) から DSBPAN_RIGHT (10,000) の範囲で、100 分の 1 デシベル (dB) 単位で測定される。値 DSBPAN_LEFT は右チャンネルが 100 dB 減衰していることを意味する。値 DSBPAN_RIGHT は左チャンネルが 100 dB 減衰していることを意味する。中立値 DSBPAN_CENTER (0) は、両方のチャンネルが最大ボリュームであることを意味する (どちらも 0 dB の減衰である)。

DSBPAN_CENTER 以外の値はいずれも、一方のチャンネルが最大ボリュームでもう一方のチャンネルが減衰していることを意味する。たとえば、値 -2173 は、左チャンネルは最大ボリュームで、右チャンネルは 21.73 dB 減衰していることを意味する。同様に、パンの値が 870 のとき、左チャンネルは 8.7 dB 減衰しており、右チャンネルは最大ボリュームであることを意味する。

パン コントロールの効果は、ボリューム コントロールに累積される。

参照

DirectSoundPrimaryBuffer8.GetPan、DirectSoundPrimaryBuffer8.SetVolume


DirectSoundPrimaryBuffer8.SetVolume

バッファのサウンド ボリュームを変更する。

object.SetVolume(volume As Long)

指定項目

object
DirectSoundPrimaryBuffer8 オブジェクトを指定する。
volume
このサウンド バッファで要求するボリューム。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかのエラー値が設定される。

DSERR_CONTROLUNAVAIL
DSERR_GENERIC
DSERR_INVALIDPARAM
DSERR_PRIOLEVELNEEDED

注意

ボリュームは減衰の 100 分の 1 デシベル (dB) 単位で指定される。設定可能な値は DSBVOLUME_MAX (減衰なし) と DSBVOLUME_MIN (無音) の間である。これらの値は、それぞれ 0、-10,000 と定義されている。値 DSBVOLUME_MAX は、サウンド本来の未調整のボリュームを表す。値 DSBVOLUME_MIN は、オーディオのボリュームが 100 dB 減衰していることを表すが、これは実際的には無音を意味する。

参照

DirectSoundPrimaryBuffer8.GetVolume、DirectSoundPrimaryBuffer8.SetPan


DirectSoundPrimaryBuffer8.Stop

サウンド バッファの再生を停止する。

object.Stop()

指定項目

object
DirectSoundPrimaryBuffer8 オブジェクトを指定する。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかのエラー値が設定される。

DSERR_INVALIDPARAM
DSERR_PRIOLEVELNEEDED

注意

アプリケーションが DSSCL_WRITEPRIMARY レベルに設定されている場合、このメソッドはプライマリ バッファを停止し、再生カーソルをバッファの先頭に設定する。これは、多くのサウンド カードのプライマリ バッファが、バッファの先頭からしか再生できないためである。

ただし、プライマリ バッファで DirectSoundPrimaryBuffer8.Stop を呼び出し、アプリケーションの協調レベルが DSSCL_WRITEPRIMARY 以外である場合、このメソッドは DirectSoundPrimaryBuffer8.Play と逆の効果を与えるだけである。セカンダリ バッファが再生されていない場合は、プライマリ バッファを停止するように構成する。同じアプリケーションまたは別のアプリケーションでほかのバッファが再生されている場合、それらのバッファが停止されるまで、プライマリ バッファも実際には停止されない。振幅が 0 dB であっても、バッファがサウンド データを再生している場合は処理のオーバーヘッドが発生するので、このメソッドを使ってプライマリ バッファを停止することは役に立つ。


DirectSoundPrimaryBuffer8.WriteBuffer

バッファにオーディオ データを書き込む。

アプリケーションから直接プライマリ バッファに書き込むことは推奨しない。DirectSoundSecondaryBuffer8.Play を呼び出すと、セカンダリ バッファのデータがプライマリ バッファにミキシングされる。

object.WriteBuffer( _
  start As Long, _
  size As Long, _
  buffer As Any, _
  flags As CONST_DSBLOCKFLAGS)

指定項目

object
DirectSoundPrimaryBuffer8 オブジェクトを指定する。
start
バッファの先頭から読み込み開始位置までのオフセット (バイト単位)。flags パラメータに定数 DSBLOCK_FROMWRITECURSOR が指定された場合、このパラメータは無視される。
size
読み込むバッファ部分のサイズ (バイト単位)。サウンド バッファは概念的には循環バッファであるため、この値はバッファの start から最後までの間のバイト数よりも大きい値になる。flags パラメータに定数 DSBLOCK_ENTIREBUFFER が指定された場合、このパラメータは無視される。
buffer
サウンド バッファに書き込むデータを含む変数。通常、これはバイトの配列であり、配列の先頭要素を渡す。
flags
データを書き込む方法を指定する CONST_DSBLOCKFLAGS 列挙の定数の 1 つ。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかのエラー コードが設定される。

DSERR_BUFFERLOST
DSERR_INVALIDCALL
DSERR_INVALIDPARAM
DSERR_PRIOLEVELNEEDED


DirectSoundSecondaryBuffer8

DirectSoundSecondaryBuffer8 クラスのオブジェクトは、セカンダリ再生バッファを表す。セカンダリ バッファからのサウンドは、プライマリ バッファにミキシングされる。

オブジェクトは、DirectSound8.CreateSoundBuffer、DirectSound8.CreateSoundBufferFromFile、または DirectSound8.CreateSoundBufferFromResource メソッドを使って取得できる。オーディオパスを使用するアプリケーションでは、DirectMusicAudioPath8.GetObjectInPath メソッドを使ってセカンダリ バッファを取得できる。

DirectSoundSecondaryBuffer8 メソッドは、次のグループにまとめることができる。

エフェクト | SetFX
情報 | GetCaps
 | GetFormat
 | GetStatus
メモリ管理 | AcquireResources
 | Restore
その他 | GetObjectInPath
 | SaveToFile
オブジェクトの取得 | GetDirectSound3DBuffer
再生管理 | GetCurrentPosition
 | Play
 | ReadBuffer
 | SetCurrentPosition
 | SetNotificationPositions
 | Stop
 | WriteBuffer
サウンド管理 | GetFrequency
 | GetPan
 | GetVolume
 | SetFrequency
 | SetPan
 | SetVolume

次の表は、オーディオパスから取得したバッファ オブジェクトに対してサポートされているメソッドを示している。オーディオパスから取得したバッファ オブジェクトとは、DirectMusic パフォーマンスによって作成されたバッファである。ミックスイン バッファは、ほかのバッファからのセンドを受け取る。オーディオパスのほかのバッファはすべて、シンクイン バッファである。これらのバッファは、シンセサイザ シンクからだけデータを受け入れる。

DirectSoundSecondaryBuffer8 method | ミックスイン | シンクイン
AcquireResources |  |
GetCaps | あり | あり
GetCurrentPosition |  |
GetDirectSound3D Buffer | あり | あり
GetFormat | あり | あり
GetFrequency |  |
GetObjectInPath | あり | あり
GetPan | あり | あり
GetStatus | あり | あり
GetVolume | あり | あり
Play | あり |
ReadBuffer |
Restore
SaveToFile
SetCurrentPosition
SetFrequency
SetFX | あり | あり
SetNotificationPositions |  |
SetPan | あり | あり
SetVolume | あり | あり
Stop | あり |
WriteBuffer |

参照

DirectSoundPrimaryBuffer8、DirectSound バッファ


DirectSoundSecondaryBuffer8.AcquireResources

DSBCAPS_LOCDEFER フラグで作成されたバッファにリソースを割り当てる。

object.AcquireResources( _
  lFlags As Long, _
  lEffectsResults() As Long)

指定項目

object
DirectSoundSecondaryBuffer8 オブジェクトを指定する。
lFlags
CONST_DSBPLAYFLAGS 列挙に含まれる、DSBPLAY_LOOPING 以外の 1 つまたは複数のフラグ。リソースを割り当てる方法を指定する。
lEffectsResults
バッファに関連付けられたエフェクトに関する情報を受け取る Long 型の変数の配列。要素の数は、あらかじめ DirectSoundSecondaryBuffer8.SetFX を使ってバッファに設定したエフェクトの数と同じでなければならない。各エフェクトに対して、CONST_DSOUNDFX 列挙のいずれかの定数が返される。
DSFXR_FAILED
リソースを利用できなかったため、エフェクトは作成されていない。
DSFXR_LOCHARDWARE
エフェクトはハードウェアでインスタンス化される。
DSFXR_LOCSOFTWARE
エフェクトはソフトウェアでインスタンス化される。
DSFXR_PRESENT
エフェクトは利用可能だが、ほかの理由でメソッドが失敗したため、作成されていない。
DSFXR_UNKNOWN
エフェクトがシステムに登録されていないため、エフェクトは作成されていない。

エラー コード

失敗した場合はエラーが発生する。Err.Number に設定される値は、次のとおりである。

DSERR_CONTROLUNAVAIL
DSERR_INVALIDCALL
DSERR_INVALIDPARAM

注意

通常、DSBCAPS_LOCDEFER で作成されたバッファには、DirectSoundSecondaryBuffer8.Play が呼び出されるまでリソースが与えられない。遅延バッファにリソースを割り当てるには、DirectSoundSecondaryBuffer8.AcquireResources を使用する。これによって、アプリケーションは、バッファを再生する前に、エフェクトの処理に関する情報を取得してエフェクト パラメータを設定できる。

このメソッドが失敗すると、lEffectsResults で、各エフェクトに対して DSFXF_PRESENT または DSFXR_UNKNOWN が返される。これらの値を調べることによって、失敗の原因となったエフェクトを特定できる。

リソースが割り当てられた未再生のバッファは、Play メソッドに渡されるボイス管理フラグによって早めに終了される候補にならない。

既に AcquireResources が呼び出されたバッファで、繰り返し AcquireResources が呼び出された場合、エフェクトのステータスは返されるが、それ以上のリソースは割り当てられない。

再生が停止すると、リソースは解放される。

ハードウェア アクセラレーションを利用できないシステムで、DSBCAPS_LOCHARDWARE フラグを使ってバッファのリソースを取得しようとすると、メソッドは失敗し、オペレーティング システムに応じて DSERR_CONTROLUNAVAIL または DSERR_INVALIDCALL を返す。


DirectSoundSecondaryBuffer8.GetCaps

バッファの能力を取得する。

object.GetCaps(caps As DSBCAPS)

指定項目

object
DirectSoundSecondaryBuffer8 オブジェクトを指定する。
caps
バッファの能力を受け取る DSBCAPS 型。

エラー コード

失敗した場合はエラーが発生し、Err.Number に DSERR_INVALIDPARAM が設定される。

注意

DSBCAPS 型は、DirectSound8.CreateSoundBuffer メソッドに渡される DSBUFFERDESC 型に情報を追加したものである。この情報として、バッファの位置 (ハードウェアとソフトウェアのどちらか) と、パフォーマンス測定値が挙げられる。

DSBCAPS 型の lFlags メンバ内のフラグは、DSBUFFERDESC 型で使われるフラグと同じものである。唯一の違いは、DSBCAPS 型ではバッファ メモリの場所に応じて DSBCAPS_LOCHARDWARE と DSBCAPS_LOCSOFTWARE のどちらかが指定されることである。DSBUFFERDESC 型ではこれらのフラグはオプションであり、フラグの指定に応じて、バッファをハードウェアとソフトウェアのどちらかに強制的に配置できる。


DirectSoundSecondaryBuffer8.GetCurrentPosition

再生カーソルと書き込みカーソルの位置を取得する。

object.GetCurrentPosition(cursors As DSCURSORS)

指定項目

object
DirectSoundSecondaryBuffer8 オブジェクトを指定する。
cursors
再生カーソルと書き込みカーソルのオフセット (バイト単位) を受け取る DSCURSORS 型。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかの値が設定される。

DSERR_INVALIDPARAM
DSERR_PRIOLEVELNEEDED

注意

書き込みカーソルは、データ書き込みを安全に行える、バッファの先頭位置である。再生カーソルより後ろ、および書き込みカーソルの前方にあるバッファには、データを書き込むべきではない。詳細については、「再生カーソルと書き込みカーソル」を参照すること。

参照

DirectSoundSecondaryBuffer8.SetCurrentPosition


DirectSoundSecondaryBuffer8.GetDirectSound3DBuffer

バッファの 3D エフェクトを操作するために使用できるオブジェクトを取得する。

object.GetDirectSound3DBuffer() As DirectSound3DBuffer8

指定項目

object
DirectSoundSecondaryBuffer8 オブジェクトを指定する。

戻り値

DirectSound3DBuffer8 オブジェクトを返す。

エラー コード

失敗すればエラーが発生し、Err.Number に E_NOINTERFACE または DSERR_OUTOFMEMORY が設定される。

注意

このメソッドは、DSBCAPS_CTRL3D フラグで作成されたバッファだけで成功する。


DirectSoundSecondaryBuffer8.GetFormat

バッファのウェーブ フォーマットの記述を取得する。

object.GetFormat(format As WAVEFORMATEX)

指定項目

object
DirectSoundSecondaryBuffer8 オブジェクトを指定する。
format
バッファのウェーブ フォーマットの記述を受け取る WAVEFORMATEX 型。

エラー コード

失敗した場合はエラーが発生し、Err.Number に DSERR_INVALIDPARAM が設定される。


DirectSoundSecondaryBuffer8.GetFrequency

バッファの再生が行われている場所の周波数を取得する。

object.GetFrequency() As Long

指定項目

object
DirectSoundSecondaryBuffer8 オブジェクトを指定する。

戻り値

周波数を Hz 単位で返す。または 1 秒あたりのサンプリング回数を返す。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかのエラー コードが設定される。

DSERR_CONTROLUNAVAIL
DSERR_INVALIDPARAM
DSERR_PRIOLEVELNEEDED

注意

周波数の値は、DSBFREQUENCY_MIN (100) から DSBFREQUENCY_MAX (100,000) の範囲をとる。

参照

DirectSoundSecondaryBuffer8.SetFrequency


DirectSoundSecondaryBuffer8.GetObjectInPath

バッファのオーディオ パス内のオブジェクトを取得する。このメソッドは一般的に、バッファまたは DMO のサウンド エフェクトを表すオブジェクトを取得するために使う。

object.GetObjectinPath( _
  guidFX As String, _
  lIndex As Long, _
  iidInterface As String _
) As Unknown

指定項目

object
DirectSoundSecondaryBuffer8 オブジェクトを指定する。
guidFX
エフェクト クラスのユニーク識別子を指定する文字列。「注意」を参照すること。DSFX で始まる AUDIOSTRINGCONSTANTS モジュールのメンバのいずれか、または文字列形式の GUID を指定する。「注意」を参照すること。
lIndex
パス中のクラスのオブジェクト内で、オブジェクトのインデックスを指定する Long 型の値。DirectSoundSecondaryBuffer8.SetFX に渡されるエフェクトの配列における、オブジェクトのインデックスである。いくつかのエフェクトがまだ作成されていない場合があるため、エフェクト チェーンにおける実際のオブジェクトの位置を表しているとは限らない。
iidInterface
返されたオブジェクトのクラスの一意な識別子を指定する String 値。ID で始まる AUDIOSTRINGCONSTANTS モジュールのメンバのいずれか、または文字列形式の GUID を指定する。「注意」を参照すること。

戻り値

エフェクトを表すオブジェクトを返す。

エラー コード

失敗した場合はエラーが発生する。Err.Number に設定される値には、DSERR_OBJECTNOTFOUND が含まれる。

注意

次の表は、エフェクトが設定されたバッファから取得できる、標準的なエフェクト オブジェクトを示している。

guidFX | iidInterface | 返されるオブジェクト
DSFX_STANDARD_CHORUS | IID_DirectSoundFXChorus | DirectSoundFXChorus8
DSFX_STANDARD_COMPRESSOR | IID_DirectSoundFXCompressor | DirectSoundFXCompressor8
DSFX_STANDARD_DISTORTION | IID_DirectSoundFXDistortion | DirectSoundFXDistortion8
DSFX_STANDARD_ECHO | IID_DirectSoundFXEcho | DirectSoundFXEcho8
DSFX_STANDARD_FLANGER | IID_DirectSoundFXFlanger | DirectSoundFXFlanger8
DSFX_STANDARD_GARGLE | IID_DirectSoundFXGargle | DirectSoundFXGargle8
DSFX_STANDARD_I3DL2REVERB | IID_DirectSoundFXI3DL2REVERB | DirectSoundFXI3DL2Reverb8
DSFX_STANDARD_PARAMEQ | IID_DirectSoundFXParamEq | DirectSoundFXParamEq8
DSFX_STANDARD_WAVES_REVERB | IID_DirectSoundFXWavesReverb | DirectSoundFXWavesReverb8

DirectSoundSecondaryBuffer8.SetFX を使用してバッファに設定されたDMO はすべて、リソースが割り当てられていない場合でも取得できる。

参照

DirectSoundSecondaryBuffer8.SetFX、GUID の使い方


DirectSoundSecondaryBuffer8.GetPan

左右のオーディオ チャンネルの相対ボリュームを取得する。

object.GetPan() As Long

指定項目

object
DirectSoundSecondaryBuffer8 オブジェクトを指定する。

戻り値

チャンネルの相対減衰を返す。「注意」を参照すること。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかのエラー コードが設定される。

DSERR_CONTROLUNAVAIL
DSERR_INVALIDPARAM
DSERR_PRIOLEVELNEEDED

注意

戻り値は、DSBPAN_LEFT (-10,000) から DSBPAN_RIGHT (10,000) の範囲で、100 分の 1 デシベル (dB) 単位で測定される。値 DSBPAN_LEFT は右チャンネルが 100 dB 減衰していることを意味する。値 DSBPAN_RIGHT は左チャンネルが 100 dB 減衰していることを意味する。中立値 DSBPAN_CENTER (0) は、両方のチャンネルが最大ボリュームであることを意味する (どちらも 0 dB の減衰である)。

DSBPAN_CENTER 以外の値はいずれも、一方のチャンネルが最大ボリュームでもう一方のチャンネルが減衰していることを意味する。たとえば、値 -2173 は、左チャンネルは最大ボリュームで、右チャンネルは 21.73 dB 減衰していることを意味する。同様に、パンの値が 870 のとき、左チャンネルは 8.7 dB 減衰しており、右チャンネルは最大ボリュームであることを意味する。

パン コントロールの効果は、ボリューム コントロールに累積される。

参照

DirectSoundSecondaryBuffer8.GetVolume、DirectSoundSecondaryBuffer8.SetPan、DirectSoundSecondaryBuffer8.SetVolume


DirectSoundSecondaryBuffer8.GetStatus

サウンド バッファのステータスを取得する。

object.GetStatus() As CONST_DSBSTATUSFLAGS

指定項目

object
DirectSoundSecondaryBuffer8 オブジェクトを指定する。

戻り値

サウンド バッファのステータスを返す。ステータスには、0、または CONST_DSBSTATUSFLAGS 列挙の定数の 1 つまたは複数を指定する。

エラー コード

失敗した場合はエラーが発生し、Err.Number が設定される。


DirectSoundSecondaryBuffer8.GetVolume

サウンド バッファのボリュームを取得する。

object.GetVolume() As Long

指定項目

object
DirectSoundSecondaryBuffer8 オブジェクトを指定する。

戻り値

バッファの減衰を 100 分の 1 デシベル単位で返す。「注意」を参照すること。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかのエラー コードが設定される。

DSERR_CONTROLUNAVAIL
DSERR_INVALIDPARAM
DSERR_PRIOLEVELNEEDED

注意

返り値は、DSBVOLUME_MAX から DSBVOLUME_MIN の範囲である。これらの定数は、それぞれ 0 および -10,000 と定義されている。値 DSBVOLUME_MAX は、サウンド本来の未調整のボリュームを表す。値 DSBVOLUME_MIN は、オーディオのボリュームが 100 dB 減衰していることを表すが、これは実際的には無音を意味する。

参照

DirectSoundSecondaryBuffer8.SetVolume、DirectSoundSecondaryBuffer8.GetPan


DirectSoundSecondaryBuffer8.Play

再生カーソルからサウンド バッファを再生する。

object.Play(flags As CONST_DSBPLAYFLAGS)

指定項目

object
DirectSoundSecondaryBuffer8 オブジェクトを指定する。
flags
CONST_DSBPLAYFLAGS 列挙の定数の 1 つまたは複数を指定する。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかのエラー コードが設定される。

DSERR_BUFFERLOST
DSERR_INVALIDCALL
DSERR_INVALIDPARAM
DSERR_PRIOLEVELNEEDED

注意

このメソッドを初めて使用する前に、アプリケーションでDirectSound8.SetCooperativeLevel メソッドを呼び出す必要がある。

メソッドで指定したバッファが既に再生中だった場合、呼び出しは成功し、バッファは再生を続ける。ただし最新の呼び出しで定義したフラグは、以前の呼び出しで定義されたフラグを置き換える。

このメソッドが DSBCAPS_LOCDEFER フラグで作成されていないバッファ上に設定されたボイス割り当てフラグ、またはボイス管理フラグで呼び出されると、この呼び出しは失敗し、DSERR_INVALIDPARAM が返される。

DSBPLAY_TERMINATEBY_TIME と DSBPLAY_TERMINATEBY_DISTANCE を組み合わせることはできないが、このどちらかと DSBPLAY_TERMINATEBY_PRIORITY を組み合わせることができる。この場合、DSBPLAY_TERMINATEBY_TIME または DSBPLAY_TERMINATEBY_DISTANCE フラグは、優先度が等しい場合にどのバッファを終了すべきかを決定するのに使われる。

次の表は、ハードウェア ボイスの空きを利用できない場合に、ボイス割り当てフラグとボイス管理フラグの組み合わせによって決まるメソッドの動作を示す。

 | DSBPLAY_LOCHARDWARE | DSBPLAY_LOCHARDWARE と DSBPLAY_LOCSOFTWARE のどちらも使わない | DSBPLAY_LOCSOFTWARE
DSBPLAY_TERMINATEBY_TIME | 再生の残り時間が最も少ないループしないサウンドを終了し、新しいサウンドを解放したボイスで再生する。 | 再生の残り時間が最も少ないループしないサウンドを終了し、新しいサウンドを解放したボイスで再生する。 | 新しいサウンドをソフトウェアで再生する。
DSBPLAY_TERMINATEBY_DISTANCE | ハードウェアで現在再生中のサウンドが最大距離を超えており、DSBCAPS_MUTE3DATMAXDISTANCE フラグが設定されている場合、そのいずれかを終了し、新しいサウンドをハードウェアで再生する。それ以外の場合、この呼び出しは失敗する。 | ハードウェアで現在再生中のサウンドが最大距離を超えており、DSBCAPS_MUTE3DATMAXDISTANCE フラグが設定されている場合、そのいずれかを終了し、新しいサウンドをハードウェアで再生する。それ以外の場合は、新しいサウンドをソフトウェアで再生する。 | 新しいサウンドをソフトウェアで再生する。
DSBPLAY_TERMINATEBY_PRIORITY | 新しいサウンドの優先度がハードウェアで現在再生中のサウンドよりも高いか同じ場合、優先度の最も低いサウンドを終了し、新しいサウンドをハードウェアで再生する。それ以外の場合、この呼び出しは失敗する。 | 新しいサウンドの優先度がハードウェアで現在再生中のサウンドよりも高いか同じ場合、優先度の最も低いサウンドを終了し、新しいサウンドをハードウェアで再生する。それ以外の場合は、新しいサウンドをソフトウェアで再生する。 | 新しいサウンドをソフトウェアで再生する。

参照

ダイナミック ボイス管理、エフェクト パラメータ


DirectSoundSecondaryBuffer8.ReadBuffer

サウンド バッファのセグメントを読み込み、アプリケーション バッファにそのデータを格納する。

セカンダリ バッファは DirectSoundSecondaryBuffer8.Play メソッドに応じて、データを自動的にプライマリ バッファに送信するため、ほとんどのアプリケーションはこのメソッドを使用しない。

object.ReadBuffer( _
  start As Long, _
  size As Long, _
  buffer As Any, _
  flags As CONST_DSBLOCKFLAGS)

指定項目

object
DirectSoundSecondaryBuffer8 オブジェクトを指定する。
start
バッファの先頭から読み込み開始位置までのオフセット (バイト単位)。flags パラメータに DSBLOCK_FROMWRITECURSOR が指定された場合、このパラメータは無視される。
size
読み込むバッファ部分のサイズ (バイト単位)。サウンド バッファは概念的には循環バッファであるため、この値はバッファの start から最後までの間のバイト数よりも大きい値になる。flags パラメータに DSBLOCK_ENTIREBUFFER が指定された場合、このパラメータは無視される。
buffer
データを受け取る変数。通常、これはバイトの配列であり、配列の先頭要素を渡す。
flags
CONST_DSBLOCKFLAGS 列挙の定数の 1 つ。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかのエラー コードが設定される。

DSERR_BUFFERLOST
DSERR_INVALIDCALL
DSERR_INVALIDPARAM
DSERR_PRIOLEVELNEEDED


DirectSoundSecondaryBuffer8.Restore

失われたサウンド バッファへのメモリ割り当てを復元する。

object.Restore()

指定項目

object
DirectSoundSecondaryBuffer8 オブジェクトを指定する。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかのエラー コードが設定される。

DSERR_BUFFERLOST
DSERR_INVALIDCALL
DSERR_PRIOLEVELNEEDED

注意

アプリケーションに入力フォーカスが置かれていないと、DirectSoundSecondaryBuffer8.Restore は成功しないことがある。たとえば、入力フォーカスが置かれているアプリケーションが DSSCL_WRITEPRIMARY (書き込み優先) 協調レベルに設定されている場合、ほかのどのアプリケーションもバッファを復元できない。

DirectSound がバッファ メモリを復元した後、有効なサウンド データを書き込み直す必要がある。DirectSound はメモリ自体を復元するが、メモリの内容は復元できない。

アプリケーションはバッファを指定して DirectSoundSecondaryBuffer8.WriteBuffer または DirectSoundSecondaryBuffer8.Play の各メソッドを呼び出すと、そのバッファが失われている場合に通知を受けられる。バッファが失われている場合、これらのメソッドは DSERR_BUFFERLOST を返す。DirectSoundSecondaryBuffer8.GetStatus メソッドを使って、サウンド バッファのステータスの取得と DSBSTATUS_BUFFERLOST フラグのテストを行うこともできる。

参照

DirectSoundSecondaryBuffer8.GetStatus、バッファ管理


DirectSoundSecondaryBuffer8.SaveToFile

バッファの内容をウェーブ ファイルに保存する。

object.SaveToFile(filename As String)

指定項目

object
DirectSoundSecondaryBuffer8 オブジェクトを指定する。
filename
サウンド バッファが保存される場所のファイル名。同じ名前のファイルが存在する場合は上書きされる。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかのエラー値が設定される。

DSERR_INVALIDCALL
DSERR_INVALIDPARAM

参照

ウェーブ ファイルへの書き込み


DirectSoundSecondaryBuffer8.SetCurrentPosition

再生カーソルの位置を設定する。

object.SetCurrentPosition(newPosition As Long)

指定項目

object
DirectSoundSecondaryBuffer8 オブジェクトを指定する。
newPosition
バッファの先頭からの再生カーソルのオフセット (バイト単位)。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかのエラー値が設定される。

DSERR_INVALIDCALL
DSERR_INVALIDPARAM
DSERR_PRIOLEVELNEEDED

注意

バッファを再生している場合、カーソルは直ちに新しい位置に移動し、再生はその場所から続行される。バッファが停止している場合は、次に DirectSoundSecondaryBuffer8.Play メソッドを呼び出したときに、新しい位置から再生を開始する。

参照

DirectSoundSecondaryBuffer8.GetCurrentPosition、再生カーソルと書き込みカーソル


DirectSoundSecondaryBuffer8.SetFrequency

サンプリング オーディオの再生周波数を設定する。

object.SetFrequency(frequency As Long)

指定項目

object
DirectSoundSecondaryBuffer8 オブジェクトを指定する。
frequency
サンプリング オーディオを再生する新しい周波数 (Hz 単位)。値の範囲は DSBFREQUENCY_MIN (100) から DSBFREQUENCY_MAX (100,000) の間でなければならない。

値が DSBFREQUENCY_ORIGINAL の場合、周波数は現在のバッファ フォーマット内のデフォルト値にリセットされる。このフォーマットは、DirectSound8.CreateSoundBuffer メソッドで指定する。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかのエラー値が設定される。

DSERR_CONTROLUNAVAIL
DSERR_GENERIC
DSERR_INVALIDPARAM
DSERR_PRIOLEVELNEEDED

注意

周波数を上下させると、オーディオ データの認識ピッチが変化する。このメソッドはバッファのフォーマットに影響を及ぼさない。

参照

DirectSoundSecondaryBuffer8.GetFrequency


DirectSoundSecondaryBuffer8.SetFX

バッファのサウンド エフェクトを設定する。バッファの再生中であってはならない。

object.SetFX( _
  EffectsCount As Long, _
  Buffers() As DSEFFECTDESC, _
  lResultIDs() As Long)

指定項目

object
DirectSoundSecondaryBuffer8 オブジェクトを指定する。
EffectsCount
Buffers および lResultIDs の要素数。0 に設定すると、バッファからすべてのエフェクトが削除される。
Buffers
設定するエフェクトを指定する DSEFFECTDESC 型の配列。
lResultIDs
Long 変数の配列。Buffers 配列の各エフェクトに対して 1 つ指定する。対応するエフェクトの作成結果に関する情報を受け取る。各要素は、CONST_DSOUNDFX 列挙の値のいずれかを受け取る。
DSFXR_LOCHARDWARE
エフェクトはハードウェアでインスタンス化される。
DSFXR_LOCSOFTWARE
エフェクトはソフトウェアでインスタンス化される。
DSFXR_UNALLOCATED
エフェクトは、ハードウェアまたはソフトウェアのいずれにもまだ設定されていない。
DSFXR_FAILED
リソースを利用できなかったため、エフェクトは作成されていない。
DSFXR_PRESENT
エフェクトは利用可能だが、ほかの理由でメソッドが失敗したため、作成されていない。
DSFXR_UNKNOWN
エフェクトがシステムに登録されていないため、エフェクトは作成されていない。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかのエラー値が設定される。

DSERR_CONTROLUNAVAIL
DSERR_GENERIC
DSERR_INVALIDPARAM
DSERR_INVALIDCALL
DSERR_NOINTERFACE
DSERR_PRIOLEVELNEEDED

注意

メソッドを成功させるには、バッファが DSBCAPS_CTRLFX フラグで作成され、バッファの再生中であってはならない。

このメソッドが失敗すると、lEffectsResults で、各エフェクトに対して DSFXF_PRESENT または DSFXR_UNKNOWN が返される。これらの値を調べることによって、失敗の原因となったエフェクトを特定できる。

メソッドから DSERR_NOINTERFACE またはその他の COM エラーが返された場合は、結果コード配列内の DSFXR_PRESENT または DSFXR_UNKNOWN を探し、エラーの原因となったエフェクトを確認する。メソッドから DSERR_INVALIDPARAM が返された場合は、DSFXR_FAILED という結果コードを探し、リソースを取得できなかったエフェクトを確認する。

バッファがオーディオパスの一部である場合、オーディオパスは非アクティブでなければならない。「DirectMusicAudioPath8.Activate」を参照すること。

エフェクト オブジェクトを取得する前に、バッファにエフェクトを設定しなければならない。エフェクト オブジェクトを取得するには、DirectSoundSecondaryBuffer8.GetObjectInPath を使う。


DirectSoundSecondaryBuffer8.SetNotificationPositions

通知位置を設定する。再生中に再生カーソルが指定されたオフセットに到達するたびに、関連するイベントがシグナル送信される。

object.SetNotificationPositions( _
  nElements As Long, _
  psa() As DSBPOSITIONNOTIFY)

指定項目

object
DirectSoundSecondaryBuffer8 オブジェクトを指定する。
nElements
psa 配列における要素数。
psa
通知位置および関連するイベントを指定する DSBPOSITIONNOTIFY 型の配列。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかのエラー コードが設定される。

DSERR_INVALIDCALL
DSERR_INVALIDPARAM
DSERR_PRIOLEVELNEEDED

参照

再生バッファの通知


DirectSoundSecondaryBuffer8.SetPan

左右のチャンネルの相対ボリュームを指定する。

object.SetPan(pan As Long)

指定項目

object
DirectSoundSecondaryBuffer8 オブジェクトを指定する。
pan
チャンネルの相対減衰を指定する値。「注意」を参照すること。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかのエラー値が設定される。

DSERR_CONTROLUNAVAIL
DSERR_GENERIC
DSERR_INVALIDPARAM
DSERR_PRIOLEVELNEEDED

注意

pan の値は DSBPAN_LEFT (-10,000) から DSBPAN_RIGHT (10,000) の範囲で、100 分の 1 デシベル (dB) 単位である。値 DSBPAN_LEFT は右チャンネルが 100 dB 減衰していることを意味する。値 DSBPAN_RIGHT は左チャンネルが 100 dB 減衰していることを意味する。中立値 DSBPAN_CENTER (0) は、両方のチャンネルが最大ボリュームであることを意味する (どちらも 0 dB の減衰である)。

DSBPAN_CENTER 以外の値はいずれも、一方のチャンネルが最大ボリュームでもう一方のチャンネルが減衰していることを意味する。たとえば、値 -2173 は、左チャンネルは最大ボリュームで、右チャンネルは 21.73 dB 減衰していることを意味する。同様に、パンの値が 870 のとき、左チャンネルは 8.7 dB 減衰しており、右チャンネルは最大ボリュームであることを意味する。

パン コントロールの効果は、ボリューム コントロールに累積される。

参照

DirectSoundSecondaryBuffer8.GetPan、DirectSoundSecondaryBuffer8.SetVolume


DirectSoundSecondaryBuffer8.SetVolume

サウンド バッファのボリュームを変更する。

object.SetVolume(volume As Long)

指定項目

object
DirectSoundSecondaryBuffer8 オブジェクトを指定する。
volume
ボリュームの減衰。単位は 100 分の 1 デシベル。「注意」を参照すること。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかのエラー値が設定される。

DSERR_CONTROLUNAVAIL
DSERR_GENERIC
DSERR_INVALIDPARAM
DSERR_PRIOLEVELNEEDED

注意

volume の値は、DSBVOLUME_MAX から DSBVOLUME_MIN の範囲でなければならない。これらの定数は、それぞれ 0 および -10,000 と定義されている。値 DSBVOLUME_MAX は、サウンド本来の未調整のボリュームを表す。値 DSBVOLUME_MIN は、オーディオのボリュームが 100 dB 減衰していることを表すが、これは実際的には無音を意味する。

参照

DirectSoundSecondaryBuffer8.GetVolume、DirectSoundSecondaryBuffer8.SetPan


DirectSoundSecondaryBuffer8.Stop

サウンド バッファの再生を停止する。

object.Stop()

指定項目

object
DirectSoundSecondaryBuffer8 オブジェクトを指定する。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかのエラー値が設定される。

DSERR_INVALIDPARAM
DSERR_PRIOLEVELNEEDED

注意

このメソッドは、バッファの再生カーソルを直前に再生されたサンプルの直後のサンプルに設定する。したがって、そのバッファに対して次に DirectSoundSecondaryBuffer8.Play メソッドを呼び出すと、以前に再生を停止した場所から再生が再開される。


DirectSoundSecondaryBuffer8.WriteBuffer

オーディオ データを保持するアプリケーション バッファから、サウンド バッファのセグメントへの書き込みを行う。

object.WriteBuffer( _
  start As Long, _
  size As Long, _
  buffer As Any, _
  flags As CONST_DSBLOCKFLAGS)

指定項目

object
DirectSoundSecondaryBuffer8 オブジェクトを指定する。
start
バッファの先頭から読み込み開始位置までのオフセット (バイト単位)。flags パラメータに定数 DSBLOCK_FROMWRITECURSOR が指定された場合、このパラメータは無視される。
size
書き込むバッファ部分のサイズ (バイト単位)。サウンド バッファは概念的には循環バッファであるため、この値はバッファの start から最後までの間のバイト数よりも大きい値になる。flags パラメータに定数 DSBLOCK_ENTIREBUFFER が指定された場合、このパラメータは無視される。
buffer
サウンド バッファに書き込むデータを含む変数。通常、これはバイトの配列であり、配列の先頭要素を渡す。
flags
データを書き込む方法を指定する CONST_DSBLOCKFLAGS 列挙の定数の 1 つ。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかのエラー コードが設定される。

DSERR_BUFFERLOST
DSERR_INVALIDCALL
DSERR_INVALIDPARAM
DSERR_PRIOLEVELNEEDED

参照

ストリーム バッファの使い方


DirectSound の型

ここでは、DirectSound で使用される次の型のリファレンス情報を記述する。

  • DS3DBUFFER
  • DS3DLISTENER
  • DSBCAPS
  • DSBPOSITIONNOTIFY
  • DSBUFFERDESC
  • DSCAPS
  • DSCBCAPS
  • DSCBUFFERDESC
  • DSCCAPS
  • DSCURSORS
  • DSEFFECTDESC
  • DSFXI3DL2REVERB
  • DSFXCHORUS
  • DSFXCOMPRESSOR
  • DSFXDISTORTION
  • DSFXECHO
  • DSFXFLANGER
  • DSFXGARGLE
  • DSFXPARAMEQ
  • DSFXWAVESREVERB
  • WAVEFORMATEX


DS3DBUFFER

3D サウンド バッファの位置、向き、動作を記述する。この型は、DirectSound3DBuffer8.GetAllParameters と DirectSound3DBuffer8.SetAllParameters の各メソッドと共に使われる。

Type DS3DBUFFER
    lConeOutsideVolume As Long
    lInsideConeAngle As Long
    lMode As CONST_DS3DMODEFLAGS
    lOutsideConeAngle As Long
    maxDistance As Single
    minDistance As Single
    vConeOrientation As D3DVECTOR
    vPosition As D3DVECTOR
    vVelocity As D3DVECTOR
End Type

メンバ

lConeOutsideVolume
サウンド コーン外部ボリューム。
lInsideConeAngle
内側サウンド プロジェクション コーンの角度。
lMode
設定される 3D サウンド処理モード。CONST_DS3DMODEFLAGS 列挙の定数のいずれかである。
lOutsideConeAngle
外側サウンド プロジェクション コーンの角度。
maxDistance
最大距離。
minDistance
最小距離。
vConeOrientation
サウンド プロジェクション コーンの向きを記述する D3DVECTOR 型。
vPosition
バッファの位置を記述する D3DVECTOR 型。
vVelocity
バッファの速度を記述する D3DVECTOR 型。


DS3DLISTENER

3D グローバル パラメータとリスナーのプロパティを記述する。この型は、DirectSound3DListener8.GetAllParameters と DirectSound3DListener8.SetAllParameters の各メソッドと共に使われる。

Type DS3DLISTENER
    distanceFactor As Single
    dopplerFactor As Single
    rolloffFactor As Single
    vOrientFront As D3DVECTOR
    vOrientTop As D3DVECTOR
    vPosition As D3DVECTOR
    vVelocity As D3DVECTOR
End Type

メンバ

distanceFactor
距離単位でのメートル数。
dopplerFactor
速度を保持するバッファに対するドップラー シフトに適用される係数。
rolloffFactor
距離によるサウンドの減衰に適用される係数。
vOrientFront
リスナーの前方を記述する D3DVECTOR 型。
vOrientTop
リスナーの上方を記述する D3DVECTOR 型。
vPosition
リスナーの位置を記述する D3DVECTOR 型。
vVelocity
リスナーの速度を記述する D3DVECTOR 型。


DSBCAPS

バッファ オブジェクトの能力を記述する。DirectSoundPrimaryBuffer8.GetCaps および DirectSoundSecondaryBuffer8.GetCaps メソッドで使われる。

Type DSBCAPS
    lBufferBytes As Long
    lFlags As CONST_DSBCAPSFLAGS
    lPlayCpuOverhead As Long
    lUnlockTransferRate As Long
End Type

メンバ

lBufferBytes
バッファのサイズ (バイト単位)。
lFlags
CONST_DSBCAPSFLAGS 列挙の定数の 1 つまたは複数を指定する。
lPlayCpuOverhead
処理のオーバーヘッド。 これは、サウンド バッファをミキシングするのに必要なメイン処理サイクルのパーセンテージとして指定される。ハードウェア バッファの場合、サウンド デバイスがミキシングを行うので、この値は 0 である。ソフトウェア バッファの場合、この値はバッファ フォーマットとシステム プロセッサの速度に依存する。
lUnlockTransferRate
データをバッファ メモリに転送する速度。 単位は 1 秒あたりのキロバイト (KB/s)。

注意

DSBCAPS 型は、DirectSound8.CreateSoundBuffer メソッドに渡される DSBUFFERDESC 型に似た情報を保持している。

DSBCAPS 型の lFlags メンバが保持するフラグは、DSBUFFERDESC 型で使われるフラグと同じものである。唯一の違いは、DSBCAPS 型ではバッファ メモリの場所に応じて DSBCAPS_LOCHARDWARE と DSBCAPS_LOCSOFTWARE のどちらかのフラグが返されることである。DSBUFFERDESC 型ではこれらのフラグはオプションであり、フラグの指定に応じて、バッファをハードウェアとソフトウェアのどちらかに強制的に配置できる。


DSBPOSITIONNOTIFY

通知位置を記述する。DirectSoundSecondaryBuffer8.SetNotificationPositions および DirectSoundCaptureBuffer8.SetNotificationPositions メソッドで使われる。

Type DSBPOSITIONNOTIFY
    hEventNotify As Long
    lOffset As Long
End Type

メンバ

hEventNotify
指定のオフセットに達したときにシグナルを送信するイベントへのハンドル。DirectX8.CreateEvent メソッドを使ってこのハンドルを取得する。
lOffset
バッファの先頭から、通知イベントがトリガされる場所までのオフセット、または DSBPN_OFFSETSTOP。「注意」を参照すること。

注意

lOffset メンバ内で値 DSBPN_OFFSETSTOP が設定されている場合、再生またはキャプチャがバッファの最後に達した (そして再生またはキャプチャがループしていない) か、アプリケーションが DirectSoundSecondaryBuffer8.Stop または DirectSoundCaptureBuffer8.Stop のどちらかのメソッドを呼び出したことが原因で、再生またはキャプチャが停止すると、イベントがシグナル送信される。

ボイス管理フラグと共に DSBCAPS_LOCDEFER と DSBCAPS_NOTIFY を使用している場合は、通知を保持するサウンドは設定できるが、到達することなくボイス管理によって終了されることもある。この場合、通知イベントは発生しない。


DSBUFFERDESC

新しい DirectSound バッファ オブジェクトの必要な特徴を記述する。この型は、DirectSound8.CreateSoundBuffer および DirectSound8.CreatePrimarySoundBuffer メソッドで使われる。

Type DSBUFFERDESC
    fxFormat As WaveFormatEx
    guid3DAlgorithm As String
    lBufferBytes As Long
    lFlags As CONST_DSBCAPSFLAGS
End Type

メンバ

fxFormat
バッファのウェーブ フォーマットを指定する WAVEFORMATEX 型。
guid3DAlgorithm
ハードウェアで 3D エフェクトを利用できないときに、DirectSound が使う二重スピーカの仮想アルゴリズムの一意な識別子。サウンド バッファに DSCAPS_CTRL3D フラグが設定されていない場合、この値は無視される。DSBCAPS_CTRL3D が lFlags に設定されていない場合、このメンバは GUID_DS3DALG_DEFAULT でなければならない。「注意」を参照すること。

AUDIOSTRINGCONSTANTS モジュールに、次のアルゴリズム識別子が定義されている。

GUID_DS3DALG_DEFAULT
DirectSound はデフォルト アルゴリズムを使用する。デフォルト アルゴリズムは、コントロール パネルの設定に基づく場合がある。多くの場合は、DS3DALG_NO_VIRTUALIZATION である。WDM ドライバでは、ユーザーがコントロール パネルでサラウンド サウンドを選択している場合、サウンドは、左、中央、右、およびサラウンド チャンネルにパンされる。

ソフトウェア ミキシングのみに適用される。WDM または VxD ドライバで利用できる。

GUID_DS3DALG_NO_VIRTUALIZATION
3D エフェクトは、標準のステレオのパンにマップされる。左に 90°のとき、サウンドは左スピーカだけから聞こえ、右に 90°のとき、サウンドは右スピーカだけから聞こえる。垂直軸では、距離によってボリュームが調節されるだけである。このバッファでは、ドップラー シフトとボリューム調節は適用されるが、3D フィルタリングは行われない。これは最も効率的なソフトウェアの実装であるが、仮想 3D オーディオ エフェクトは提供しない。DS3DALG_NO_VIRTUALIZATION フラグを指定すると、HRTF 処理は行われない。DS3DALG_NO_VIRTUALIZATION は標準のステレオのパンのみを使うので、このアルゴリズムで作成されたバッファは、3D ハードウェア ボイスの空きを利用できない場合、2D ハードウェア ボイスによってアクセラレートされる。

ソフトウェア ミキシングのみに適用される。WDM または VxD ドライバで利用できる。

GUID_DS3DALG_HRTF_FULL
3-D エフェクトは、高品質な 3D オーディオ アルゴリズムで処理される。このアルゴリズムは最高品質の 3D オーディオ エフェクトを与えるが、より多くの CPU サイクルを使う。「注意」を参照すること。

ソフトウェア ミキシングのみに適用される。WDM ドライバを使った、Microsoft® Windows® 98 Second Edition および Windows 2000 で利用できる。

GUID_DS3DALG_HRTF_LIGHT
3D エフェクトは、効率的な 3D オーディオ アルゴリズムで処理される。このアルゴリズムは優れた 3D オーディオ エフェクトを与え、DS3DALG_HRTF_FULL ほど CPU に負荷をかけない。「注意」を参照すること。

ソフトウェア ミキシングのみに適用される。WDM ドライバを使うと、Windows 98 Second Edition および Windows 2000 で利用できる。

lBufferBytes
バッファのサイズ (バイト単位)。DSBCAPS_PRIMARYBUFFER フラグを使用してバッファを作成した場合、この値は 0 でなければならない。セカンダリ バッファのサイズは、4 から &H0FFFFFFF (268,435,455) までの範囲でなければならない。
lFlags
バッファの能力を識別するフラグ。0、または CONST_DSBCAPSFLAGS 列挙の 1 つ以上の定数を指定する。

注意

DSBCAPS_LOCHARDWARE および DSBCAPS_LOCSOFTWARE フラグはオプションであり、互いに排他的である。DSBCAPS_LOCHARDWARE は、強制的にバッファをハードウェアに配置する。これは、バッファがサウンド カードによってミキシングされることを意味する。DSBCAPS_LOCSOFTWARE は、強制的にバッファをソフトウェアに配置する。この場合、バッファは CPU によってミキシングされる。これらのフラグは DSBCAPS 型の lFlags メンバにも返され、バッファの実際の場所を示す。

3D アルゴリズムは、ソフトウェア エミュレーション レイヤのみの選択を行う。これは、アクセラレーション用のハードウェアがない場合に使われるソフトウェア アルゴリズムである。ハードウェアの利用を最大にするために、DS3DALG_NO_VIRTUALIZATION は特別な場合として扱われる。3D ハードウェア ボイスの空きを利用できない場合、バッファは 3D API コントロールと共に 2D バッファとして扱われる。特に、サウンド バッファを DS3DALG_NO_VIRTUALIZATION で作成する場合、または DSBPLAY_LOCDEFER で作成されたバッファを再生する場合は、次の手順に従う。

  • 利用可能な 3D ハードウェア ボイスがある場合は、その 3D ハードウェア ボイスを使う。
  • 利用可能な 3D ハードウェア ボイスがなく、2D ハードウェア ボイスを利用可能な場合は、その 2D ハードウェア ボイスを使う。これが可能なのは、DS3DALG_NO_VIRTUALIZATION アルゴリズムが単純なステレオ パン アルゴリズムだからである。
  • 利用できる 2D または 3D ハードウェア ボイスの空きがない場合、ボイスは DS3DALG_NO_VIRTUALIZATION アルゴリズムを使ってソフトウェアで再生される。

DSSPEAKER_HEADPHONE または DSSPEAKER_STEREO 以外のスピーカ構成が有効な場合、処理は二重スピーカ構成に対する処理と同じように行われる。

バッファが HRTF アルゴリズムのいずれかを使って作成され、システムで HRTF アルゴリズムを利用できない場合 (たとえば、非 WDM システムである場合)、メソッドは成功するが、サウンド バッファは代わりに DS3DALG_NO_VIRTUALIZATION を使う。


DSCAPS

DirectSound デバイスの能力を記述する。DirectSound8.GetCaps メソッドで使われる。

Type DSCAPS
    lFlags As CONST_DSCAPSFLAGS
    lFreeHw3DAllBuffers As Long
    lFreeHw3DStaticBuffers As Long
    lFreeHw3DStreamingBuffers As Long
    lFreeHwMemBytes As Long
    lFreeHwMixingAllBuffers As Long
    lFreeHwMixingStaticBuffers As Long
    lFreeHwMixingStreamingBuffers As Long
    lMaxContigFreeHwMemBytes As Long
    lMaxHw3DAllBuffers As Long
    lMaxHw3DStaticBuffers As Long
    lMaxHw3DStreamingBuffers As Long
    lMaxHwMixingAllBuffers As Long
    lMaxHwMixingStaticBuffers As Long
    lMaxHwMixingStreamingBuffers As Long
    lMaxSecondarySampleRate As Long
    lMinSecondarySampleRate As Long
    lPlayCpuOverheadSwBuffers As Long
    lPrimaryBuffers As Long
    lReserved1 As Long
    lReserved2 As Long
    lTotalHwMemBytes As Long
    lUnlockTransferRateHwBuffers As Long
End Type

メンバ

lFlags
デバイス能力。CONST_DSCAPSFLAGS 列挙の 1 つ以上の定数を指定する。
lFreeHw3DAllBuffers
未割り当ての 3D バッファの数。
lFreeHw3DStaticBuffers
未割り当てのスタティック 3D バッファの数。
lFreeHw3DStreamingBuffers
未割り当てのストリーム 3D バッファの数。
lFreeHwMemBytes
サウンド カードの空きメモリのサイズ (バイト単位)。
lFreeHwMixingAllBuffers
未割り当てのバッファの数。WDM ドライバでは、lFreeHw3DAllBuffers を含む。
lFreeHwMixingStaticBuffers
未割り当てのスタティック バッファの数。
lFreeHwMixingStreamingBuffers
未割り当てのストリーム バッファの数。
lMaxContigFreeHwMemBytes
サウンド カード上の空きメモリのうち、最大の連続ブロックのサイズ (バイト単位)。
lMaxHw3DAllBuffers
3D バッファの最大数。
lMaxHw3DStaticBuffers
スタティック 3D バッファの最大数。
lMaxHw3DStreamingBuffers
ストリーム 3D バッファの最大数。
lMaxHwMixingAllBuffers
ハードウェアでミキシングできるバッファの合計数。このメンバには lMaxHwMixingStaticBuffers と lMaxHwMixingStreamingBuffers の合計より小さい値を指定する。リソースのトレードオフがしばしば発生する。
lMaxHwMixingStaticBuffers
スタティック サウンド バッファの最大数。
lMaxHwMixingStreamingBuffers
ストリーム サウンド バッファの最大数。
lMaxSecondarySampleRate、lMinSecondarySampleRate
このデバイスのハードウェア セカンダリ サウンド バッファがサポートする最小と最大のサンプリング レートの仕様。
lPlayCpuOverheadSwBuffers
(メイン システム メモリ内の) ソフトウェア バッファをミキシングするのに必要な処理オーバーヘッドを、CPU パーセンテージで記述した値。この値は、バス タイプ、プロセッサ タイプ、およびクロック速度に応じて変化する。

ソフトウェア バッファのアンロック転送速度は、データをどこにも転送する必要がないため 0 である。同様に、ハードウェア バッファの再生オーバーヘッドも、ミキシングがサウンド デバイスによって処理されるため 0 である。

lPrimaryBuffers
サポートされているプライマリ バッファの数。この値は常に 1 である。
lReserved1、lReserved2
予約済み。
lTotalHwMemBytes
スタティック サウンド バッファを保持するサウンド カード上のメモリ容量のサイズ (バイト単位)。
lUnlockTransferRateHwBuffers
ハードウェア スタティック サウンド バッファへのデータ転送速度。 単位は 1 秒あたりのキロバイト (KB/s)。

注意

オーディオ サウンド カードによっては、利用可能なハードウェア バッファやその空きを正確に報告できない場合がある。これはたとえば、カードが、高いサンプリング レートよりも低いサンプリング レートでより多くのサウンドを再生できるときに発生する。通常、ハードウェア バッファの空き数に関係するメンバの値が 0 以外の場合は、適切なタイプのハードウェア リソースが少なくとも 1 つ利用できることを示している。


DSCBCAPS

キャプチャ バッファの能力を記述する。DirectSoundCaptureBuffer8.GetCaps メソッドで使われる。

Type DSCBCAPS
    lBufferBytes As Long
    lFlags As CONST_DSCBCAPSFLAGS
    lReserved As Long
End Type

メンバ

lBufferBytes
キャプチャ バッファのサイズ (バイト単位)。
lFlags
デバイス能力を記述するフラグ。CONST_DSCBCAPSFLAGS 列挙の定数の 1 つ。
lReserved
予約済み。


DSCBUFFERDESC

キャプチャ バッファを記述する。DirectSoundCapture8.CreateCaptureBuffer メソッドで使われる。

Type DSCBUFFERDESC
    fxFormat As WAVEFORMATEX
    guid3DAlgorithm As String
    lBufferBytes As Long
    lFlags As CONST_DSCBCAPSFLAGS
End Type

メンバ

fxFormat
データのキャプチャに使うフォーマットを保持する WAVEFORMATEX 型。
guid3DAlgorithm
未使用。
lBufferBytes
作成されるキャプチャ バッファのサイズ (バイト単位)。
lFlags
デバイスの能力を指定するフラグ。CONST_DSCBCAPSFLAGS 列挙の定数の 1 つ。


DSCCAPS

キャプチャ デバイスの能力を記述する。DirectSoundCapture8.GetCaps メソッドで使われる。

Type DSCCAPS
    lChannels As Long
    lFlags As CONST_DSCCAPSFLAGS
    lFormats As CONST_WAVEFORMATFLAGS
End Type

メンバ

lChannels
デバイスがサポートするチャンネル数。 1 はモノラル、2 はステレオを意味する。 以下同様である。
lFlags
デバイス能力。CONST_DSCCAPSFLAGS 列挙のメンバのいずれかを指定する。
lFormats
サポートされている標準フォーマット。CONST_WAVEFORMATFLAGS 列挙の 1 つ以上の定数を指定する。


DSCURSORS

再生カーソルおよび書き込みカーソルの位置を DirectSoundSecondaryBuffer8.GetCurrentPosition メソッドに返す。同様に、キャプチャ カーソルと読み込みカーソルの位置を DirectSoundCaptureBuffer8.GetCurrentPosition メソッドに返す。

Type DSCURSORS
    lPlay As Long
    lWrite As Long
End Type

メンバ

lPlay
再生バッファ中の再生カーソル、またはキャプチャ バッファ中のキャプチャ カーソル。
lWrite
再生バッファ中の書き込みカーソル、またはキャプチャ バッファ中の読み込みカーソル。

注意

値はバッファの先頭からのオフセットであり、単位はバイトである。

lPlay が表すカーソルは、lWrite が表すカーソルのわずか前方にある。2 つのカーソル間のバッファ部分は、読み書きの準備ができていない。lWrite までの位置では、アプリケーションはキャプチャ バッファからのデータの読み込みと、再生バッファへのデータの書き込みを安全に行うことができる。

参照

再生カーソルと書き込みカーソル、キャプチャ バッファの情報


DSEFFECTDESC

バッファに関連付けられているエフェクトを記述する。

Type DSEFFECTDESC
    guidDSFXClass As String
    lFlags As Long
End Type

メンバ

guidDSFXClass
エフェクトのクラス識別子を指定する String。次に示す標準エフェクトのエイリアス、または GUID を使用できる。
DSFX_STANDARD_CHORUS
DSFX_STANDARD_COMPRESSOR
DSFX_STANDARD_DISTORTION
DSFX_STANDARD_ECHO
DSFX_STANDARD_FLANGER
DSFX_STANDARD_GARGLE
DSFX_STANDARD_I3DL2REVERB
DSFX_STANDARD_PARAMEQ
DSFX_STANDARD_WAVES_REVERB
lFlags
バッファ作成オプションを指定するフラグ。0、または CONST_DSOUNDFX 列挙の次のいずれかの値を指定する。
DSFX_LOCHARDWARE
エフェクトはハードウェアになければならない。ハードウェアでエフェクトを利用できない場合、DirectSoundSecondaryBuffer8.SetFX はエラーを発生させる。DirectX 8.0 は、エフェクトのハードウェア アクセラレーションをサポートしないため、このフラグを使用すべきではない。
DSFX_LOCSOFTWARE
ハードウェアが guidDSFXClass のアクセラレーションをサポートする場合でも、エフェクトはソフトウェアになければならない。ソフトウェアでエフェクトを利用できない場合、SetFX はエラーを発生させる。DirectX 8.0 では、このフラグが設定されているかどうかにかかわらず、エフェクトはすべてソフトウェアに存在する。

注意

lFlags が 0 の場合、可能であればエフェクトはハードウェアに配置される。ハードウェアがエフェクトをサポートしていない場合は、ソフトウェアが使われる。エフェクトがまったく利用できない場合は、SetFX を呼び出すとエラーが発生する。

DSFX_STANDARD_WAVES_REVERB クラスのエフェクトは、16 ビットのオーディオ フォーマットを備えるバッファ上にのみ設定できる。

参照

エフェクトの使い方


DSFXI3DL2REVERB

I3DL2 (Interactive 3D Audio Level 2) リバーブ エフェクトのパラメータを保持する。

Type DSFXI3DL2REVERB
    fDecayHFRatio As Single
    fDecayTime As Single
    fDensity As Single
    fDiffusion As Single
    fHFReference As Single
    fReflectionsDelay As Single
    fReverbDelay As Single
    fRoomRolloffFactor As Single
    lReflections As Long
    lReverb As Long
    lRoom As Long
    lRoomHF As Long
End Type

メンバ

fDecayHFRatio
高周波数のディケイ時間と低周波数のディケイ時間の比率。値の範囲は 0.1 ～ 2。デフォルト値は、0.83 である。
fDecayTime
ディケイ時間。値の範囲は 0.1 ～ 20 秒。デフォルト値は 1.49 秒である。
fDensity
後期リバーブ ディケイのモーダル密度。デフォルト値は 100.0% である。最小値および最大値は、CONST_DSFX_I3DL2REVERB_DENSITY 列挙に定義されている。
fDiffusion
後期リバーブ ディケイのエコー密度。デフォルト値は 100.0% である。最小値および最大値は、CONST_DSFX_I3DL2REVERB_DIFFUSION 列挙に定義されている。
fHFReference
参照高周波数。デフォルト値は 5000,0 である。最小値および最大値は、CONST_DSFX_I3DL2REVERB_HFREFERENCE 列挙に定義されている。
fReflectionsDelay
ダイレクト パスを基準とする、初期反射の遅延時間。値の範囲は 0 ～ 0.3 秒。デフォルト値は 0.007 秒である。
fReverbDelay
最初の反射の時間を基準とする、初期反射と後期リバーブ間の制限時間。値の範囲は 0 ～ 0.1 秒。デフォルト値は 0.011 秒である。
fRoomRolloffFactor
反射信号のロールオフ係数。デフォルト値は 0.0 である。最小値および最大値は、CONST_DSFX_I3DL2REVERB_ROOMROLLOFFFACTOR 列挙に定義されている。ダイレクト パスのロールオフ係数は、DirectSound リスナーによって制御されている。
lReflections
lRoom を基準とする初期反射の減衰。デフォルト値は、-2602 mB である。最小値および最大値は、CONST_DSFX_I3DL2REVERB_REFLECTIONS 列挙に定義されている。
lReverb
lRoom を基準とする後期リバーブの減衰。デフォルト値は、-200 mB である。最小値および最大値は、CONST_DSFX_I3DL2REVERB_REVERB 列挙に定義されている。
lRoom
空間エフェクトの減衰。デフォルト値は、-1000 mB である。最小値および最大値は、CONST_DSFX_I3DL2REVERB_ROOM 列挙に定義されている。
lRoomHF
空間高周波数エフェクトの減衰。デフォルト値は 0 mB である。最小値および最大値は、CONST_DSFX_I3DL2REVERB_ROOMHF 列挙に定義されている。


DSFXCHORUS

コーラス エフェクトのパラメータを保持する。

Type DSFXCHORUS
    fDelay As Single
    fDepth As Single
    fFeedback As Single
    fFrequency As Single
    fWetDryMix As Single
    lPhase As CONST_DSFX_PHASE
    lWaveform As CONST_DSFX_WAVE
End Type

メンバ

fDelay
再生される前に入力が遅延する時間数 (ミリ秒単位)。デフォルト値は 0 である。最小値および最大値は、CONST_DSFX_DELAY 列挙に定義されている。
fDepth
低周波数発振器によって乗算される遅延時間のパーセンテージ (パーセンテージ単位)。デフォルト値は 25 である。最小値および最大値は、CONST_DSFX_DEPTH 列挙に定義されている。
fFeedback
エフェクトの入力にフィードバックされる出力信号のパーセンテージ。デフォルト値は 0 である。最小値および最大値は、CONST_DSFX_FEEDBACK 列挙に定義されている。
fFrequency
LFO の周波数。デフォルト値は 0 である。最小値および最大値は、CONST_DSFX_FREQUENCY 列挙に定義されている。
fWetDryMix
ウェット (処理済み) シグナルとドライ (未処理) シグナルの比。最小値および最大値は、CONST_DSFX_WETDRY 列挙に定義されている。
lPhase
左右の LFO の位相差。指定可能な値は、CONST_DSFX_PHASE 列挙に定義されている。デフォルト値は 0 である。
lWaveform
LFO のウェーブフォーム。デフォルトでは、ウェーブフォームはサインである。指定可能な値は、CONST_DSFX_WAVE 列挙に定義されている。

注意

メンバの型が最小値および最大値を定義する列挙である場合、この定義の範囲内のその他の Long 値が認められる。最小値および最大値はコードの記述時に簡単にアクセスできるので、この列挙は便利である。

参照

DirectSoundFXChorus8、コーラス


DSFXCOMPRESSOR

圧縮エフェクトのパラメータを保持する。

Type DSFXCOMPRESSOR
    fAttack As Single
    fGain As Single
    fPreDelay As Single
    fRatio As Single
    fRelease As Single
    fThreshold As Single
End Type

    メンバ

    fAttack
    圧縮が最大値に達するまでの時間。デフォルト値は 0.01 ms である。最小値および最大値は、CONST_DSFXCOMPRESSOR_ATTACK 列挙に定義されている。「注意」を参照すること。
    fGain
    圧縮後の信号の出力ゲイン。デフォルト値は 0 dB である。最小値および最大値は、CONST_DSFXCOMPRESSOR_GAIN 列挙に定義されている。
    fPreDelay
    lThreshold に達してからアタック フェーズが開始されるまでの時間。デフォルト値は 0 ms である。最小値および最大値は、CONST_DSFXCOMPRESSOR_PREDELAY 列挙に定義されている。
    fRatio
    圧縮率。デフォルト値は 10 で、この値は 10:1 の圧縮を表している。最小値および最大値は、CONST_DSFXCOMPRESSOR_RATIO 列挙に定義されている。
    fRelease
    入力が lThreshold 以下になった後に圧縮を停止する速度。デフォルト値は 50 ms である。最小値および最大値は、CONST_DSFXCOMPRESSOR_RELEASE 列挙に定義されている。
    fThreshold
    圧縮を開始するポイント。デフォルト値は -10 dB である。最小値および最大値は、CONST_DSFXCOMPRESSOR_THRESHOLD 列挙に定義されている。

    注意

    便宜上、fAttack の最小値は、CONST_DSFXCOMPRESSOR_ATTACK 列挙内に整数 1 として定義されている。ただし、実際の最小値は、デフォルト値でもある 0.01 である。

    参照

    DirectSoundFXCompressor8、コンプレッション


DSFXDISTORTION

ディストーション エフェクトのパラメータを保持する。

Type DSFXDISTORTION
    fEdge As Single
    fGain As Single
    fPostEQBandwidth As Single
    fPostEQCenterFrequency As Single
    fPreLowpassCutoff As Single
End Type

    メンバ

    fEdge
    ディストーション強度のパーセンテージ。デフォルト値は 50 である。最小値および最大値は、CONST_DSFXDISTORTION_EDGE 列挙に定義されている。
    fGain
    ディストーション後の信号の変化量 (デシベル単位)。デフォルト値は 0 である。最小値および最大値は、CONST_DSFXDISTORTION_GAIN 列挙に定義されている。
    fPostEQBandwidth
    追加する倍音成分の周波数帯域の幅 (Hz 単位)。デフォルト値は 4000 である。最小値および最大値は、CONST_DSFXDISTORTION_POSTEQBANDWIDTH 列挙に定義されている。
    fPostEQCenterFrequency
    追加する倍音成分の中心周波数 (Hz 単位)。デフォルト値は 4000 である。最小値および最大値は、CONST_DSFXDISTORTION_POSTEQCENTERFREQUENCY 列挙に定義されている。
    fPreLowpassCutoff
    高周波数倍音減衰のフィルタ カットオフ (Hz 単位)。デフォルト値は 4000 である。最小値および最大値は、CONST_DSFXDISTORTION_PRELOWPASSCUTOFF 列挙に定義されている。

    注意

    fPostEQBandwidth、fPostEQCenterFrequency、および fPreLowpassCutoff の値は、バッファの周波数の 3 分の 1 を超えることはできない。

    参照

    DirectSoundFXDistortion8、ディストーション


DSFXECHO

エコー エフェクトのパラメータを保持する。

Type DSFXECHO
    fFeedback As Single
    fLeftDelay As Single
    fRightDelay As Single
    fWetDryMix as Single
    lPanDelay As CONST_DSFX_PANDELAY
End Type

メンバ

fFeedback
入力にフィードバックする出力のパーセンテージ。デフォルト値は 0 である。最小値および最大値は、CONST_DSFXECHO_FEEDBACK 列挙に定義されている。
fLeftDelay
左チャンネルの遅延。デフォルト値は 333 ms である。最小値および最大値は、CONST_DSFX_LEFTRIGHTDELAY 列挙に定義されている。
fRightDelay
右チャンネルの遅延。デフォルト値は 333 ms である。最小値および最大値は、CONST_DSFX_LEFTRIGHTDELAY 列挙に定義されている。
fWetDryMix
ウェット (処理済み) シグナルとドライ (未処理) シグナルの比。最小値および最大値は、CONST_DSFX_WETDRY 列挙に定義されている。
lPanDelay
連続する各エコーで、左右の遅延を入れ替えるかどうかを指定する値。デフォルト値は 0 で、入れ替えを行わない。指定可能な値は、CONST_DSFX_PANDELAY 列挙に定義されている。

注意

メンバの型が最小値および最大値を定義する列挙である場合、この定義の範囲内のその他の Long 値が認められる。最小値および最大値はコードの記述時に簡単にアクセスできるので、この列挙は便利である。

参照

DirectSoundFXEcho8、エコー


DSFXFLANGER

フランジ エフェクトのパラメータを保持する。

Type DSFXFLANGER
    fDelay As Single
    fDepth As Single
    fFeedback As Single
    fFrequency As Single
    fWetDryMix As Single
    lPhase As CONST_DSFX_PHASE
    lWaveform As CONST_DSFX_WAVE
End Type

メンバ

fDelay
再生される前に入力が遅延する時間数 (ミリ秒単位)。デフォルト値は 0 である。最小値および最小値は、CONST_DSFX_FLANGER_DELAY 列挙に定義されている。
fDepth
低周波数発振器によって乗算される遅延時間のパーセンテージ (パーセンテージ単位)。デフォルト値は 25 である。最小値および最大値は、CONST_DSFX_DEPTH 列挙に定義されている。
fFeedback
エフェクトの入力にフィードバックされる出力信号のパーセンテージ。デフォルト値は 0 である。最小値および最大値は、CONST_DSFX_FEEDBACK 列挙に定義されている。
fFrequency
LFO の周波数。デフォルト値は 0 である。最小値および最大値は、CONST_DSFX_FREQUENCY 列挙に定義されている。
fWetDryMix
ウェット (処理済み) シグナルとドライ (未処理) シグナルの比。最小値および最大値は、CONST_DSFX_WETDRY 列挙に定義されている。
lPhase
左右の LFO の位相差。指定可能な値は、CONST_DSFX_PHASE 列挙に定義されている。デフォルト値は 0 である。
lWaveform
LFO のウェーブフォーム。デフォルトでは、ウェーブフォームはサインである。指定可能な値は、CONST_DSFX_WAVE 列挙に定義されている。

注意

メンバの型が最小値および最大値を定義する列挙である場合、この定義の範囲内のその他の Long 値が認められる。最小値および最大値はコードの記述時に簡単にアクセスできるので、この列挙は便利である。

参照

DirectSoundFXFlanger8、フランジ


DSFXGARGLE

DirectSoundFXGargle8 オブジェクトで表される、振幅変調エフェクトのパラメータを保持する。

Type DSFXGARGLE
    lRateHz As CONST_DSFXGARGLE_RATEHZ
    lWaveShape As CONST_DSFXGARGLE_WAVE
End Type

メンバ

lRateHz
変調率 (Hz 単位)。最小値および最大値は、CONST_DSFXGARGLE_RATEHZ 列挙に定義されている。この範囲内の Long 値であれば有効である。
lWaveShape
変調波の形状。指定可能な値は、CONST_DSFXGARGLE_WAVE 列挙に定義されている。

参照

DirectSoundFXGargle8、ガーグル


DSFXPARAMEQ

パラメトリック イコライザ エフェクトのパラメータを保持する。

Type DSFXPARAMEQ
    fBandwidth As Single
    fCenter As Single
    fGain As Single
End Type

メンバ

fBandwidth
帯域幅 (半音単位)。最小値および最大値は、CONST_DSFXPARAMEQ_BANDWIDTH 列挙に定義されている。
fCenter
中心周波数 (Hz 単位)。最小値および最大値は、CONST_DSFXPARAMEQ_CENTER 列挙に定義されている。この値は、バッファの周波数の 3 分の 1 を超えることはできない。
fGain
ゲイン (デシベル単位)。最小値および最大値は、CONST_DSFXPARAMEQ_GAIN 列挙に定義されている。

参照

DirectSoundFXParamEq8、パラメトリック イコライザ


DSFXWAVESREVERB

DirectSoundFXWavesReverb8 オブジェクトで表されるミュージック リバーブ エフェクトのパラメータを保持する。

Type DSFXWavesReverb
    fHighFreqRTRatio As Long
    fInGain As Long
    fReverbMix As Long
    fReverbTime As Long
End Type

メンバ

fHighFreqRTRatio
値の範囲は、0.001 ～ 0.999。デフォルト値は 0.001 である。
fInGain
信号の入力ゲイン。単位はデシベル (dB)。デフォルト値は 0.0 である。最小値および最大値は、CONST_DSFX_WAVESREVERB_INGAIN 列挙に定義されている。
fReverbMix
リバーブ ミックス。単位はデシベル (dB)。デフォルト値は 0 である。最小値および最大値は、CONST_DSFX_WAVESREVERB_REVERBMIX 列挙に定義されている。
fReverbTime
リバーブ タイム (ミリ秒単位)。値の範囲は、0.001 ～ 3000.0。デフォルト値は 1000.0 である。


WAVEFORMATEX

ウェーブフォーム オーディオ データのフォーマットを定義する。

Type WAVEFORMATEX
    lAvgBytesPerSec As Long
    lExtra As Long
    lSamplesPerSec As Long
    nBitsPerSample As Integer
    nBlockAlign As Integer
    nChannels As Integer
    nFormatTag As Integer
    nSize As Integer
End Type

メンバ

lAvgBytesPerSec
フォーマット用に要求された平均データ転送速度。 単位は 1 秒あたりのバイト数である。nFormatTag が WAVE_FORMAT_PCM の場合、nAvgBytesPerSec は lSamplesPerSec と nBlockAlign の積に等しくなる。
lExtra
未使用。 0 に設定する。
lSamplesPerSec
各チャンネルの再生や録音におけるサンプリング レート。 単位は 1 秒あたりのサンプリング回数 (Hz)。nFormatTag が WAVE_FORMAT_PCM の場合、lSamplesPerSec の通常の値は 8.0 kHz、11.025 kHz、22.05 kHz、および 44.1 kHz である。
nBitsPerSample
サンプリングあたりのビット数。nFormatTag が WAVE_FORMAT_PCM の場合、nBitsPerSample は 8 か 16 でなければならない。
nBlockAlign
ブロック整列 (バイト単位)。ブロック アライメントは、nFormatTag フォーマット タイプのデータの最小単位である。nFormatTag が WAVE_FORMAT_PCM の場合、nBlockAlign は 8 (バイトあたりのビット数) で割った nChannels と nBitsPerSample の積に等しくなる。

バッファに読み書きされるデータは、常にブロックの先頭で開始しなければならない。たとえば、PCM データの再生を、サンプルの中間、つまり非ブロック整列の境界から開始するのは間違いである。

nChannels
ウェーブフォーム オーディオ データのチャンネル数。モノラル データは 1 つのチャンネルを使い、ステレオ データは 2 つのチャンネルを使う。
nFormatTag
ウェーブフォーム オーディオ フォーマットのタイプ。DirectSound では、このメンバが常に WAVE_FORMAT_PCM でなければならない。
nSize
追加フォーマット情報のサイズ (バイト単位)。WAVE_FORMAT_PCM フォーマットでは、このメンバは無視される。


DirectSound の列挙

DirectSound は列挙を使用し、Visual Basic のステートメント補完機能を利用して定数をグループ化する。DirectSound で使用する列挙を次に示す。

  • CONST_DS3DAPPLYFLAGS
  • CONST_DS3DMODEFLAGS
  • CONST_DSBCAPSFLAGS
  • CONST_DSBLOCKFLAGS
  • CONST_DSBPLAYFLAGS
  • CONST_DSBSTATUSFLAGS
  • CONST_DSCAPSFLAGS
  • CONST_DSCBCAPSFLAGS
  • CONST_DSCBLOCKFLAGS
  • CONST_DSCBSTARTFLAGS
  • CONST_DSCBSTATUSFLAGS
  • CONST_DSCCAPSFLAGS
  • CONST_DSFX_DELAY
  • CONST_DSFX_DEPTH
  • CONST_DSFXECHO_FEEDBACK
  • CONST_DSFX_FEEDBACK
  • CONST_DSFX_FLANGER_DELAY
  • CONST_DSFX_FREQUENCY
  • CONST_DSFX_I3DL2_ENVIRONMENT_PRESETS
  • CONST_DSFX_I3DL2REVERB_DENSITY
  • CONST_DSFX_I3DL2REVERB_DIFFUSION
  • CONST_DSFX_I3DL2REVERB_HFREFERENCE
  • CONST_DSFX_I3DL2REVERB_QUALITY
  • CONST_DSFX_I3DL2REVERB_REFLECTIONS
  • CONST_DSFX_I3DL2REVERB_REVERB
  • CONST_DSFX_I3DL2REVERB_ROOM
  • CONST_DSFX_I3DL2REVERB_ROOMHF
  • CONST_DSFX_I3DL2REVERB_ROOMROLLOFFFACTOR
  • CONST_DSFX_LEFTRIGHTDELAY
  • CONST_DSFX_PANDELAY
  • CONST_DSFX_PHASE
  • CONST_DSFX_WAVE
  • CONST_DSFX_WAVESREVERB_INGAIN
  • CONST_DSFX_WAVESREVERB_REVERBMIX
  • CONST_DSFX_WETDRY
  • CONST_DSFXCOMPRESSOR_ATTACK
  • CONST_DSFXCOMPRESSOR_GAIN
  • CONST_DSFXCOMPRESSOR_PREDELAY
  • CONST_DSFXCOMPRESSOR_RATIO
  • CONST_DSFXCOMPRESSOR_RELEASE
  • CONST_DSFXCOMPRESSOR_THRESHOLD
  • CONST_DSFXDISTORTION_EDGE
  • CONST_DSFXDISTORTION_GAIN
  • CONST_DSFXDISTORTION_POSTEQBANDWIDTH
  • CONST_DSFXDISTORTION_POSTEQCENTERFREQUENCY
  • CONST_DSFXDISTORTION_PRELOWPASSCUTOFF
  • CONST_DSFXGARGLE_RATEHZ
  • CONST_DSFXGARGLE_WAVE
  • CONST_DSFXPARAMEQ_BANDWIDTH
  • CONST_DSFXPARAMEQ_CENTER
  • CONST_DSFXPARAMEQ_GAIN
  • CONST_DSOUND
  • CONST_DSOUNDERR
  • CONST_DSOUNDFX
  • CONST_DSSCLFLAGS
  • CONST_DSSPEAKERFLAGS
  • CONST_WAVEFORMATFLAGS


CONST_DS3DAPPLYFLAGS

DirectSound3DBuffer8 および DirectSound3DListener8 クラスのさまざまなメソッドのパラメータで使用される。この列挙のメンバは、新しい設定を適用する時期を指定するために使用される。

Enum CONST_DS3DAPPLYFLAGS
    DS3D_DEFERRED  = 1
    DS3D_IMMEDIATE = 0
End Enum

定数

DS3D_DEFERRED
アプリケーションが DirectSound3DListener8.CommitDeferredSettings メソッドを呼び出すまで設定を適用しない。
DS3D_IMMEDIATE
即時に設定を適用する。

注意

いくつかのパラメータをすぐに変更する場合は、それらに DS3D_DEFERRED のフラグを設定し、1 回の呼び出しでコミットするとより効率的である。


CONST_DS3DMODEFLAGS

DirectSound3DBuffer8.GetMode および DirectSound3DBuffer8.SetMode メソッドで使用され、3D サウンド処理の操作モードの設定と取得を行う。

Enum CONST_DS3DMODEFLAGS
    DS3DMODE_DISABLE      = 2
    DS3DMODE_HEADRELATIVE = 1
    DS3DMODE_NORMAL       = 0
End Enum

定数

DS3DMODE_DISABLE
3D サウンド処理は無効になる。サウンドは、リスナーの頭の中心で発生しているように聞こえる。
DS3DMODE_HEADRELATIVE
サウンド パラメータ (位置、速度、および向き) は、リスナーのパラメータに対する相対的なものである。このモードでは、リスナーのパラメータが変化したときにサウンドの絶対パラメータが更新されるので、相対パラメータは一定に保たれる。
DS3DMODE_NORMAL
サウンド パラメータは、ワールド空間に対する相対的なものである。これはデフォルトのモードである。


CONST_DSBCAPSFLAGS

DSBUFFERDESC 型で使用され、新しいバッファの能力を指定する。また、DSBCAPS で使用する場合は、既存のバッファの能力を記述する。

Enum CONST_DSBCAPSFLAGS
    DSBCAPS_CTRL3D              =     16 (&H10)
    DSBCAPS_CTRLCHANNELVOLUME   =   1024 (&H400)
    DSBCAPS_CTRLFREQUENCY       =     32 (&H20)
    DSBCAPS_CTRLFX              =    512 (&H200)
    DSBCAPS_CTRLPAN             =     64 (&H40)
    DSBCAPS_CTRLPOSITIONNOTIFY  =    256
    DSBCAPS_CTRLVOLUME          =    128 (&H80)
    DSBCAPS_GETCURRENTPOSITION2 =  65536 (&H10000)
    DSBCAPS_GLOBALFOCUS         =  32768 (&H8000)
    DSBCAPS_LOCDEFER            = 262144 (&H40000)
    DSBCAPS_LOCHARDWARE         =      4
    DSBCAPS_LOCSOFTWARE         =      8
    DSBCAPS_MUTE3DATMAXDISTANCE = 131072 (&H20000)
    DSBCAPS_PRIMARYBUFFER       =      1
    DSBCAPS_STATIC              =      2
    DSBCAPS_STICKYFOCUS         =  16384 (&H4000)
End Enum

定数

DSBCAPS_CTRL3D
バッファは 3D コントロールをサポートする。
DSBCAPS_CTRLCHANNELVOLUME
実装されていない。
DSBCAPS_CTRLFREQUENCY
バッファは周波数コントロールをサポートする。DSBCAPS_CTRLFX と組み合わせることはできない。
DSBCAPS_CTRLFX
バッファはエフェクトをサポートする。DSBCAPS_CTRLFREQUENCY と組み合わせることはできない。ウェーブ フォーマットは、2 チャンネル以下の 8 ビットまたは 16 ビットの PCM フォーマットでなければならない。
DSBCAPS_CTRLPAN
バッファはパン コントロールをサポートする。
DSBCAPS_CTRLPOSITIONNOTIFY
バッファは位置通知をサポートする。「注意」を参照すること。
DSBCAPS_CTRLVOLUME
バッファはボリューム コントロールをサポートする。
DSBCAPS_GETCURRENTPOSITION2
DirectSoundSecondaryBuffer8.GetCurrentPosition は、再生カーソルの新しい動作を使用する。このフラグは常にセカンダリ バッファに設定する。
DSBCAPS_GLOBALFOCUS
バッファはグローバルなサウンド バッファである。このフラグを設定すると、ユーザーがほかのアプリケーションにフォーカスを移動し、その新しいアプリケーションが DirectSound を使用する場合でも、DirectSound を使用しているアプリケーションは引き続きそのバッファを再生できる。ただし、フォーカスを移動した DirectSound アプリケーションが、協調レベルに DSSCL_WRITEPRIMARY フラグを使用している場合、ほかのアプリケーションからのグローバルなサウンドは聞こえなくなる。
DSBCAPS_LOCDEFER
バッファは、再生されるまでハードウェアまたはソフトウェアに割り当てられない。ボイス管理を使用するバッファでは、このフラグを設定しなければならない。
DSBCAPS_LOCHARDWARE
バッファはハードウェア ミキシングを使用する。デバイスがハードウェア ミキシングをサポートしていない場合や、必要なハードウェア メモリが利用不可能な場合は、DirectSound8.CreateSoundBuffer メソッドの呼び出しは失敗する。アプリケーションは、このバッファがミキシング チャンネルを利用可能であることを保証する必要がある。 この状況は保証されていない。
DSBCAPS_LOCSOFTWARE
DSBCAPS_STATIC が指定され、ハードウェア リソースを利用できる場合でも、バッファはソフトウェア ミキシングを使用する。
DSBCAPS_MUTE3DATMAXDISTANCE
リスナーからの距離が最大距離を超えるとバッファの再生が停止するので、プロセッサ時間を消費しないで済む。
DSBCAPS_PRIMARYBUFFER
バッファはプライマリ サウンド バッファである。DSBCAPS_CTRLFX と組み合わせることはできない。
DSBCAPS_STATIC
利用可能な場合、バッファはサウンド カードのメモリ上に配置される。バッファを強制的にメモリ (通常はドライバが管理するシステム メモリ) に配置する DSBCAPS_LOCHARDWARE とは異なる。DSBCAPS_CTRLFX と組み合わせることはできない。
DSBCAPS_STICKYFOCUS
バッファはスティッキー フォーカスを備えている。ユーザーが DirectSound を使用していないほかのアプリケーションに切り替えた場合でも、DirectSound を使用しているアプリケーションはスティッキー フォーカス バッファの再生を続行できる。この状態ではアプリケーションの標準バッファは無音になるが、スティッキー フォーカス バッファは引き続き音を出す。ユーザーがほかのアプリケーションを使用しながら、ゲーム以外のアプリケーションのサウンドトラックを聞きたいと考える場合に役立つ。しかし、ユーザーがほかの DirectSound アプリケーションに切り替えると、今までのアプリケーションのすべてのサウンド バッファ、この場合は標準バッファとスティッキー フォーカス バッファの両方が無音になる。

注意

バッファが作成されるとき、DSBCAPS_LOCHARDWARE および DSBCAPS_LOCSOFTWARE フラグはオプションであり、互いに排他的である。DSBCAPS_LOCHARDWARE は、強制的にバッファをハードウェアに配置する。これは、バッファがサウンド カードによってミキシングされることを意味する。DSBCAPS_LOCSOFTWARE は、強制的にバッファをソフトウェアに配置する。この場合、バッファは CPU によってミキシングされる。DSBCAPS 型では、フラグはバッファの実際の場所を示す。

DSBCAPS_CTRLPOSITIONNOTIFY フラグを使用してサウンド バッファを作成したが、通知を設定しなかった場合は、動作が定義されず、サウンドが 2 回再生される場合がある。

VxD ドライバでは、サウンド バッファが DSBCAPS_CTRLPOSITIONNOTIFY で作成される場合、バッファは常にソフトウェア バッファになる。このフラグ設定で作成されたバッファの再生中は、DSBPLAY_LOCHARDWARE フラグによる DirectSoundSecondaryBuffer8.Play の呼び出しは失敗する。ハードウェアが利用可能な場合、WDM ドライバにより、通知可能なバッファはハードウェアに存在することができる。


CONST_DSBLOCKFLAGS

DirectSoundSecondaryBuffer8.ReadBuffer および DirectSoundSecondaryBuffer8.WriteBuffer メソッドの flags パラメータで使用され、読み込みまたは書き込みを行うバッファの部分を指定する。

Enum CONST_DSBLOCKFLAGS
    DSBLOCK_DEFAULT         = 0
    DSBLOCK_ENTIREBUFFER    = 2
    DSBLOCK_FROMWRITECURSOR = 1
End Enum

定数

DSBLOCK_DEFAULT
start パラメータで指定された位置からの読み込みと書き込みを行う。
DSBLOCK_ENTIREBUFFER
バッファ全体から読み込む、またはバッファ全体に書き込む。size パラメータは無視される。
DSBLOCK_FROMWRITECURSOR
書き込みカーソルで読み込みまたは書き込みを行う。start パラメータは無視される。


CONST_DSBPLAYFLAGS

DirectSoundSecondaryBuffer8.Play メソッドの flags パラメータで使用され、バッファの再生方法を指定する。

Enum CONST_DSBPLAYFLAGS
    DSBPLAY_DEFAULT              =  0
    DSBPLAY_LOCHARDWARE          =  2
    DSBPLAY_LOCSOFTWARE          =  4
    DSBPLAY_LOOPING              =  1
    DSBPLAY_TERMINATEBY_DISTANCE = 16 (&H10)
    DSBPLAY_TERMINATEBY_PRIORITY = 32 (&H20)
    DSBPLAY_TERMINATEBY_TIME     =  8
End Enum

定数

DSBPLAY_DEFAULT
再生カーソルからオーディオ バッファの最後までを再生する。
DSBPLAY_LOCHARDWARE
ハードウェア バッファのみでこのボイスを再生する。ハードウェアに利用可能なボイスがない場合、またはボイス管理フラグが設定されていない場合、DirectSoundsSecondaryBuffer8.Play の呼び出しは失敗する。このフラグを DSBPLAY_LOCSOFTWARE と組み合わせることはできない。
DSBPLAY_LOCSOFTWARE
ソフトウェア バッファのみでこのボイスを再生する。このフラグを DSBPLAY_LOCHARDWARE または任意の DSBPLAY_TERMINATEBY フラグと組み合わせることはできない。
DSBPLAY_LOOPING
再生カーソルからバッファの最後までを再生し、バッファの先頭で再生を再開する。明示的に停止するまでバッファの再生は続けられる。
DSBPLAY_TERMINATEBY_DISTANCE
ハードウェアに利用可能なボイスがない場合、現在再生中のバッファは、新しいバッファに空きを確保するために停止する。早めに終了されるバッファは、DSBCAPS_MUTE3DATMAXDISTANCE フラグが設定され、最大距離を超えているものの中から選択される。このようなバッファがない場合、メソッドは失敗する。
DSBPLAY_TERMINATEBY_PRIORITY
ハードウェアに利用可能なボイスがない場合、現在再生中のバッファは、新しいバッファに空きを確保するために停止する。
DSBPLAY_TERMINATEBY_TIME
ハードウェアに利用可能なボイスがない場合、現在再生中のバッファは、新しいバッファに空きを確保するために停止する。早めに終了されるバッファは、再生の残り時間が最も少ないバッファである。


CONST_DSBSTATUSFLAGS

バッファのステータスを記述する。この列挙の定数は、DirectSoundSecondaryBuffer8.GetStatus メソッドによって返される。

Enum CONST_DSBSTATUSFLAGS
    DSBSTATUS_BUFFERLOST  =  2
    DSBSTATUS_LOCHARDWARE =  8
    DSBSTATUS_LOCSOFTWARE = 16 (&H10)
    DSBSTATUS_LOOPING     =  4
    DSBSTATUS_PLAYING     =  1
    DSBSTATUS_TERMINATED  = 32 (&H20)
End Enum

定数

DSBSTATUS_BUFFERLOST
バッファは失われており、再生やロックを行う前に復元しなければならない。
DSBSTATUS_LOCHARDWARE
バッファはハードウェアで再生中である。DSBCAPS_LOCDEFER フラグで作成したバッファにのみ設定する。
DSBSTATUS_LOCSOFTWARE
バッファはソフトウェアで再生中である。DSBCAPS_LOCDEFER フラグで作成したバッファにのみ設定する。
DSBSTATUS_LOOPING
バッファはループしている。この値が設定されていない場合、サウンド データの最後に達するとバッファが停止する。この値は、DSBSTATUS_PLAYING との組み合わせでのみ返される。
DSBSTATUS_PLAYING
バッファは再生中である。
DSBSTATUS_TERMINATED
ボイス管理がバッファを早めに終了し、バッファは停止している。DSBCAPS_LOCDEFER フラグで作成したバッファにのみ設定する。


CONST_DSCAPSFLAGS

DSCAPS 型の lFlags メンバで使用され、デバイスの能力を記述する。

Enum CONST_DSCAPSFLAGS
    DSCAPS_CERTIFIED       =   64 (&H40)
    DSCAPS_CONTINUOUSRATE  =   16 (&H10)
    DSCAPS_EMULDRIVER      =   32 (&H20)
    DSCAPS_PRIMARY16BIT    =    8
    DSCAPS_PRIMARY8BIT     =    4
    DSCAPS_PRIMARYMONO     =    1
    DSCAPS_PRIMARYSTEREO   =    2
    DSCAPS_SECONDARY16BIT  = 2048 (&H800)
    DSCAPS_SECONDARY8BIT   = 1024 (&H400)
    DSCAPS_SECONDARYMONO   =  256 (&H100)
    DSCAPS_SECONDARYSTEREO =  512 (&H200)
End Enum

定数

DSCAPS_CERTIFIED
このドライバは Microsoft でテストされ、認定されている。このフラグは常に WDM ドライバに対して設定されるが、依存すべきではない。
DSCAPS_CONTINUOUSRATE
このデバイスは、lMinSecondarySampleRate と lMaxSecondarySampleRate の各メンバ値の間のすべてのサンプリング レートをサポートする。一般にこれは、実際の出力レートが要求された周波数の ±10 ヘルツ (Hz) 以内であることを意味する。
DSCAPS_EMULDRIVER
このデバイスには DirectSound ドライバがインストールされていない。 ウェーブフォーム オーディオ機能を通してエミュレートされている。性能の低下が予想される。
DSCAPS_PRIMARY16BIT
このデバイスは 16 ビット サンプリングでプライマリ サウンド バッファをサポートする。
DSCAPS_PRIMARY8BIT
このデバイスは 8 ビット サンプリングでプライマリ バッファをサポートする。
DSCAPS_PRIMARYMONO
このデバイスはモノラルのプライマリ バッファをサポートする。
DSCAPS_PRIMARYSTEREO
このデバイスはステレオのプライマリ バッファをサポートする。
DSCAPS_SECONDARY16BIT
このデバイスは、16 ビット サンプリングでハードウェア ミキシングのセカンダリ サウンド バッファをサポートする。
DSCAPS_SECONDARY8BIT
このデバイスは、8 ビット サンプリングでハードウェア ミキシングのセカンダリ バッファをサポートする。
DSCAPS_SECONDARYMONO
このデバイスは、ハードウェア ミキシングのモノラル セカンダリ バッファをサポートする。
DSCAPS_SECONDARYSTEREO
このデバイスは、ハードウェア ミキシングのステレオ セカンダリ バッファをサポートする。


CONST_DSCBCAPSFLAGS

DSCBCAPS 型の lFlags メンバで使用され、デバイスの能力を指定する。

Enum CONST_DSCBCAPSFLAGS
    DSCBCAPS_DEFAULT    =           0
    DSCBCAPS_WAVEMAPPED = -2147483648 (&H80000000)
End Enum

定数

DSCBCAPS_WAVEMAPPED
デバイスがサポートしないフォーマットに対して、Win32 ウェーブ マッパーを使用する。


CONST_DSCBLOCKFLAGS

DirectSoundCaptureBuffer8.ReadBuffer および DirectSoundCaptureBuffer8.WriteBuffer メソッドによって使用され、サウンド キャプチャ バッファからの読み込みとそのバッファへの書き込みを指定する。

Enum CONST_DSCBLOCKFLAGS
    DSCBLOCK_DEFAULT      = 0
    DSCBLOCK_ENTIREBUFFER = 1
End Enum

定数

DSCBLOCK_DEFAULT
start パラメータの指定するオフセットで読み込みと書き込みを行う。
DSCBLOCK_ENTIREBUFFER
バッファ全体から読み込む、またはバッファ全体に書き込む。size パラメータは無視される。start が 0 でない場合、データ転送は start で開始し、バッファの先頭までラップ アラウンドする。


CONST_DSCBSTARTFLAGS

DirectSoundCaptureBuffer8.Start メソッドの flags メンバで使用され、サウンド データのキャプチャリングのときにキャプチャ バッファの動作を指定する。

Enum CONST_DSCBSTARTFLAGS
    DSCBSTART_DEFAULT = 0
    DSCBSTART_LOOPING = 1
End Enum

定数

DSCBSTART_DEFAULT
バッファの最後に達するとキャプチャは停止する。
DSCBSTART_LOOPING
バッファの最後に達したら、先頭からキャプチャを再開し、明示的に停止されるまで続行する。


CONST_DSCBSTATUSFLAGS

キャプチャ バッファのステータスを記述し、DirectSoundCaptureBuffer8.GetStatus メソッドで返される。

Enum CONST_DSCBSTATUSFLAGS
    DSCBSTATUS_CAPTURING = 1
    DSCBSTATUS_LOOPING   = 2
End Enum

定数

DSCBSTATUS_CAPTURING
キャプチャ バッファはサウンド データをキャプチャしている。
DSCBSTATUS_LOOPING
キャプチャ バッファはループしている。この値は、常に DSCBSTATUS_CAPTURING との組み合わせで返される。


CONST_DSCCAPSFLAGS

DSCCAPS 型の lFlags メンバで使用され、キャプチャ デバイスの能力を記述する。

Enum CONST_DSCCAPSFLAGS
    DSCCAPS_DEFAULT    =  0
    DSCCAPS_EMULDRIVER = 32 (&H20)
End Enum

定数

DSCCAPS_DEFAULT
デバイスは DirectSound キャプチャ可能である。
DSCCAPS_EMULDRIVER
デバイスに対して利用可能なドライバがないため、標準のウェーブ オーディオ機能が使用されている。


CONST_DSFX_DELAY

DSFXCHORUS 型で使用される。

Enum CONST_DSFX_DELAY
    DSFX_DELAY_MAX = 20 (&H14)
    DSFX_DELAY_MIN =  0
End Enum

定数

DSFX_DELAY_MAX
最大値。
DSFX_DELAY_MIN
最小値。


CONST_DSFX_DEPTH

DSFXCHORUS 型および DSFXFLANGER 型で使用される。

Enum CONST_DSFX_DEPTH
    DSFX_DEPTH_MAX  = 100 (&H64)
    DSFX_DEPTH_MIN  =   0
End Enum

定数

DSFX_DEPTH_MAX
最大値。
DSFX_DEPTH_MIN
最小値。


CONST_DSFXECHO_FEEDBACK

DSFXECHO 型で使用される。

Enum CONST_DSFXECHO_FEEDBACK
    DSFXECHO_FEEDBACK_MAX  = 100 (&H64)
    DSFXECHO_FEEDBACK_MIN  =   0
End Enum

定数

DSFXECHO_FEEDBACK_MAX
最大値。
DSFXECHO_FEEDBACK_MIN
最小値。


CONST_DSFX_FEEDBACK

DSFXCHORUS 型および DSFXFLANGER 型で使用される。

Enum CONST_DSFX_FEEDBACK
    DSFX_FEEDBACK_MAX  =  99 (&H63)
    DSFX_FEEDBACK_MIN  = -99 (&HFFFFFF9D)
End Enum

定数

DSFX_FEEDBACK_MAX
最大値。
DSFX_FEEDBACK_MIN
最小値。


CONST_DSFX_FLANGER_DELAY

DSFXFLANGER 型で使用される。

Enum CONST_DSFX_FLANGER_DELAY
    DSFX_FLANGER_DELAY_MAX =  4
    DSFX_FLANGER_DELAY_MIN =  0
End Enum

定数

DSFX_FLANGER_DELAY_MAX
最大値。
DSFX_FLANGER_DELAY_MIN
最小値。


CONST_DSFX_FREQUENCY

DSFXCHORUS 型および DSFXFLANGER 型で使用される。

Enum CONST_DSFX_FREQUENCY
    DSFX_FREQUENCY_MAX        = 10
    DSFX_FREQUENCY_MIN        = 0
End Enum

定数

DSFX_FREQUENCY_MAX
最大値。
DSFX_FREQUENCY_MIN
最小値。


CONST_DSFX_I3DL2_ENVIRONMENT_PRESETS

DirectSoundFXI3DL2Reverb8 のメソッドで使用され、定義済みのエフェクト パラメータのセットを識別する。

Enum CONST_DSFX_I3DL2_ENVIRONMENT_PRESETS
    DSFX_I3DL2_ENVIRONMENT_PRESET_ALLEY         = 15
    DSFX_I3DL2_ENVIRONMENT_PRESET_ARENA         = 10
    DSFX_I3DL2_ENVIRONMENT_PRESET_AUDITORIUM    =  7
    DSFX_I3DL2_ENVIRONMENT_PRESET_BATHROOM      =  4
    DSFX_I3DL2_ENVIRONMENT_PRESET_CARPETEDHALLWAY=12
    DSFX_I3DL2_ENVIRONMENT_PRESET_CAVE          =  9
    DSFX_I3DL2_ENVIRONMENT_PRESET_CITY          = 17 (&H11)
    DSFX_I3DL2_ENVIRONMENT_PRESET_CONCERTHALL   =  8
    DSFX_I3DL2_ENVIRONMENT_PRESET_DEFAULT       =  0
    DSFX_I3DL2_ENVIRONMENT_PRESET_FOREST        = 16 (&H10)
    DSFX_I3DL2_ENVIRONMENT_PRESET_GENERIC       =  1
    DSFX_I3DL2_ENVIRONMENT_PRESET_HALLWAY       = 13
    DSFX_I3DL2_ENVIRONMENT_PRESET_HANGAR        = 11
    DSFX_I3DL2_ENVIRONMENT_PRESET_LARGEHALL     = 28 (&H1C)
    DSFX_I3DL2_ENVIRONMENT_PRESET_LARGEROOM     = 26 (&H1A)
    DSFX_I3DL2_ENVIRONMENT_PRESET_LIVINGROOM    =  5
    DSFX_I3DL2_ENVIRONMENT_PRESET_MEDIUMHALL    = 27 (&H1B)
    DSFX_I3DL2_ENVIRONMENT_PRESET_MEDIUMROOM    = 25 (&H19)
    DSFX_I3DL2_ENVIRONMENT_PRESET_MOUNTAINS     = 18 (&H12)
    DSFX_I3DL2_ENVIRONMENT_PRESET_PADDEDCELL    =  2
    DSFX_I3DL2_ENVIRONMENT_PRESET_PARKINGLOT    = 21 (&H15)
    DSFX_I3DL2_ENVIRONMENT_PRESET_PLAIN         = 20 (&H14)
    DSFX_I3DL2_ENVIRONMENT_PRESET_PLATE         = 29 (&H1D)
    DSFX_I3DL2_ENVIRONMENT_PRESET_QUARRY        = 19 (&H13)
    DSFX_I3DL2_ENVIRONMENT_PRESET_ROOM          =  3
    DSFX_I3DL2_ENVIRONMENT_PRESET_SEWERPIPE     = 22 (&H16)
    DSFX_I3DL2_ENVIRONMENT_PRESET_SMALLROOM     = 24 (&H18)
    DSFX_I3DL2_ENVIRONMENT_PRESET_STONECORRIDOR = 14
    DSFX_I3DL2_ENVIRONMENT_PRESET_STONEROOM     =  6
    DSFX_I3DL2_ENVIRONMENT_PRESET_UNDERWATER    = 23 (&H17)
End Enum

定数

あらかじめ設定される各定数に関連する値のリストについては、「Dsound.h」を参照すること。


CONST_DSFX_I3DL2REVERB_DENSITY

DSFXI3DL2REVERB 型の fDensity メンバで使用される。

Enum CONST_DSFX_I3DL2REVERB_DENSITY
    DSFX_I3DL2REVERB_DENSITY_DEFAULT = 100 (&H64)
    DSFX_I3DL2REVERB_DENSITY_MAX     = 100 (&H64)
    DSFX_I3DL2REVERB_DENSITY_MIN     =   0
End Enum

定数

DSFX_I3DL2REVERB_DENSITY_DEFAULT
デフォルト値。
DSFX_I3DL2REVERB_DENSITY_MAX
最大値。
DSFX_I3DL2REVERB_DENSITY_MIN
最小値。


CONST_DSFX_I3DL2REVERB_DIFFUSION

DSFXI3DL2REVERB 型の fDiffusion メンバで使用される。

Enum CONST_DSFX_I3DL2REVERB_DIFFUSION
    DSFX_I3DL2REVERB_DIFFUSION_DEFAULT = 100 (&H64)
    DSFX_I3DL2REVERB_DIFFUSION_MAX     = 100 (&H64)
    DSFX_I3DL2REVERB_DIFFUSION_MIN     =   0
End Enum

定数

DSFX_I3DL2REVERB_DIFFUSION_DEFAULT
デフォルト値。
DSFX_I3DL2REVERB_DIFFUSION_MAX
最大値。
DSFX_I3DL2REVERB_DIFFUSION_MIN
最小値。


CONST_DSFX_I3DL2REVERB_HFREFERENCE

DSFXI3DL2REVERB 型の fHFReference メンバで使用される。

Enum CONST_DSFX_I3DL2REVERB_HFREFERENCE
    DSFX_I3DL2REVERB_HFREFERENCE_DEFAULT =  5000 (&H1388)
    DSFX_I3DL2REVERB_HFREFERENCE_MAX     = 20000 (&H4E20)
    DSFX_I3DL2REVERB_HFREFERENCE_MIN     =    20 (&H14)
End Enum

定数

DSFX_I3DL2REVERB_HFREFERENCE_DEFAULT
デフォルト値。
DSFX_I3DL2REVERB_HFREFERENCE_MAX
最大値。
DSFX_I3DL2REVERB_HFREFERENCE_MIN
最小値。


CONST_DSFX_I3DL2REVERB_QUALITY

DirectSoundFXI3DL2Reverb8.SetQuality メソッドの lQuality パラメータで使用される。

Enum CONST_DSFX_I3DL2REVERB_REFLECTIONS
    DSFX_I3DL2REVERB_QUALITY_DEFAULT = 2
    DSFX_I3DL2REVERB_QUALITY_MAX     = 3
    DSFX_I3DL2REVERB_QUALITY_MIN     = 0
End Enum

定数

DSFX_I3DL2REVERB_QUALITY_DEFAULT
デフォルト値。
DSFX_I3DL2REVERB_QUALITY_MAX
最大値。
DSFX_I3DL2REVERB_QUALITY_MIN
最小値。


CONST_DSFX_I3DL2REVERB_REFLECTIONS

DSFXI3DL2REVERB 型の lReflectionsDelay メンバで使用される。

Enum CONST_DSFX_I3DL2REVERB_REFLECTIONS
    DSFX_I3DL2REVERB_REFLECTIONS_DEFAULT = -10000 (&HFFFFD8F0)
    DSFX_I3DL2REVERB_REFLECTIONS_MAX     =   1000 (&H3E8)
    DSFX_I3DL2REVERB_REFLECTIONS_MIN     = -10000 (&HFFFFD8F0)
End Enum

定数

DSFX_I3DL2REVERB_REFLECTIONS_DEFAULT
デフォルト値。
DSFX_I3DL2REVERB_REFLECTIONS_MAX
最大値。
DSFX_I3DL2REVERB_REFLECTIONS_MIN
最小値。


CONST_DSFX_I3DL2REVERB_REVERB

DSFXI3DL2REVERB 型の lReverbDelay メンバで使用される。

Enum CONST_DSFX_I3DL2REVERB_REVERB
    DSFX_I3DL2REVERB_REVERB_DEFAULT = -10000 (&HFFFFD8F0)
    DSFX_I3DL2REVERB_REVERB_MAX =       2000 (&H7D0)
    DSFX_I3DL2REVERB_REVERB_MIN     = -10000 (&HFFFFD8F0)
End Enum

定数

DSFX_I3DL2REVERB_REVERB_DEFAULT
デフォルト値。
DSFX_I3DL2REVERB_REVERB_MAX
最大値。
DSFX_I3DL2REVERB_REVERB_MIN
最小値。


CONST_DSFX_I3DL2REVERB_ROOM

DSFXI3DL2REVERB 型の lRoom メンバで使用される。

Enum CONST_DSFX_I3DL2REVERB_ROOM
    DSFX_I3DL2REVERB_ROOM_DEFAULT = -10000 (&HFFFFD8F0)
    DSFX_I3DL2REVERB_ROOM_MAX     =      0
    DSFX_I3DL2REVERB_ROOM_MIN     = -10000 (&HFFFFD8F0)
End Enum

定数

DSFX_I3DL2REVERB_ROOM_DEFAULT
デフォルト値。
DSFX_I3DL2REVERB_ROOM_MAX
最大値。
DSFX_I3DL2REVERB_ROOM_MIN
最小値。


CONST_DSFX_I3DL2REVERB_ROOMHF

DSFXI3DL2REVERB 型の lRoomHF メンバで使用される。

Enum CONST_DSFX_I3DL2REVERB_ROOMHF
    DSFX_I3DL2REVERB_ROOMHF_DEFAULT =      0
    DSFX_I3DL2REVERB_ROOMHF_MAX     =      0
    DSFX_I3DL2REVERB_ROOMHF_MIN     = -10000 (&HFFFFD8F0)
End Enum

定数

DSFX_I3DL2REVERB_ROOMHF_DEFAULT
デフォルト値。
DSFX_I3DL2REVERB_ROOMHF_MAX
最大値。
DSFX_I3DL2REVERB_ROOMHF_MIN
最小値。


CONST_DSFX_I3DL2REVERB_ROOMROLLOFFFACTOR

DSFXI3DL2REVERB 型の lRoomRolloffFactor メンバで使用される。

Enum CONST_DSFX_I3DL2REVERB_ROOMROLLOFFFACTOR
    DSFX_I3DL2REVERB_ROOMROLLOFFFACTOR_DEFAULT = 0
    DSFX_I3DL2REVERB_ROOMROLLOFFFACTOR_MAX     = 1
    DSFX_I3DL2REVERB_ROOMROLLOFFFACTOR_MIN     = 0
End Enum

定数

DSFX_I3DL2REVERB_ROOMROLLOFFFACTOR_DEFAULT
デフォルト値。
DSFX_I3DL2REVERB_ROOMROLLOFFFACTOR_MAX
最大値。
DSFX_I3DL2REVERB_ROOMROLLOFFFACTOR_MIN
最小値。


CONST_DSFX_LEFTRIGHTDELAY

DSFXECHO 型で使用される。

Enum CONST_DSFX_LEFTRIGHTDELAY
    DSFX_LEFTRIGHTDELAY_MAX = 2000 (&H7D0)
    DSFX_LEFTRIGHTDELAY_MIN =    1
End Enum

定数

DSFX_LEFTRIGHTDELAY_MAX
最大値。
DSFX_LEFTRIGHTDELAY_MIN
最小値。


CONST_DSFX_PANDELAY

DSFXECHO 型で使用される。

Enum CONST_DSFX_PANDELAY
    DSFX_PANDELAY_MAX = 1
    DSFX_PANDELAY_MIN = 0
End Enum

定数

DSFX_PANDELAY_MAX
最大値。TRUE と同じ値である。
DSFX_PANDELAY_MIN
最小値。FALSE と同じ値である。


CONST_DSFX_PHASE

DSFXCHORUS 型および DSFXFLANGER 型で使用される。

Enum CONST_DSFX_PHASE
    DSFX_PHASE_180     = 4
    DSFX_PHASE_90      = 3
    DSFX_PHASE_MAX     = 4
    DSFX_PHASE_MIN     = 0
    DSFX_PHASE_NEG_180 = 0
    DSFX_PHASE_NEG_90  = 1
    DSFX_PHASE_ZERO    = 2
End Enum

定数

DSFX_PHASE_180
ウェーブフォームの下降中間点。
DSFX_PHASE_90
ウェーブフォームの最頂点。
DSFX_PHASE_MAX
最大値。
DSFX_PHASE_MIN
最小値。
DSFX_PHASE_NEG_180
ウェーブフォームの上昇中間点。
DSFX_PHASE_NEG_90
ウェーブフォームの最下点。
DSFX_PHASE_ZERO
ウェーブフォームの上昇中間点。


CONST_DSFX_WAVE

DSFXCHORUS 型および DSFXFLANGER 型で使用される。

Enum CONST_DSFX_WAVE
    DSFX_WAVE_SIN       = 1
    DSFX_WAVE_TRIANGLE  = 0
End Enum

定数

DSFX_WAVE_SIN
正弦波。
DSFX_WAVE_TRIANGLE
三角波。


CONST_DSFX_WAVESREVERB_INGAIN

DSFXWAVESREVERB 型の fInGain メンバで使用される。

Enum CONST_DSFX_WAVESREVERB_INGAIN
    DSFX_WAVESREVERB_INGAIN_MAX  =   0
    DSFX_WAVESREVERB_INGAIN_MIN  = -96 (&HFFFFFFA0)
End Enum

定数

DSFX_WAVESREVERB_INGAIN_MAX
最大値。
DSFX_WAVESREVERB_INGAIN_MIN
最小値。


CONST_DSFX_WAVESREVERB_REVERBMIX

DSFXWAVESREVERB 型の fReverbMix メンバで使用される。

Enum CONST_DSFX_WAVESREVERB_REVERBMIX
    DSFX_WAVESREVERB_REVERBMIX_MAX  = 0
    DSFX_WAVESREVERB_REVERBMIX_MIN  = -96 (&HFFFFFFA0)
End Enum

定数

DSFX_WAVESREVERB_REVERBMIX_MAX
最大値。
DSFX_WAVESREVERB_REVERBMIX_MIN
最小値。


CONST_DSFX_WETDRY

DSFXCHORUS 型、DSFXECHO 型、および DSFXFLANGER 型で使用される。

Enum CONST_DSFX_WETDRY
    DSFX_WETDRYMIX_MAX = 100 (&H64)
    DSFX_WETDRYMIX_MIN =   0
End Enum

定数

DSFX_WETDRYMIX_MAX
最大値。
DSFX_WETDRYMIX_MIN
最小値。


CONST_DSFXCOMPRESSOR_ATTACK

DSFXCOMPRESSOR 型の fAttack メンバで使用される。

Enum CONST_DSFXCOMPRESSOR_ATTACK
    DSFXCOMPRESSOR_ATTACK_MAX = 500 (&H1F4)
    DSFXCOMPRESSOR_ATTACK_MIN =   1
End Enum

定数

DSFXCOMPRESSOR_ATTACK_MAX
最大値。
DSFXCOMPRESSOR_ATTACK_MIN
最小値。


CONST_DSFXCOMPRESSOR_GAIN

DSFXCOMPRESSOR 型の fGain メンバで使用される。

Enum CONST_DSFXCOMPRESSOR_GAIN
    DSFXCOMPRESSOR_GAIN_MAX =  60 (&H3C)
    DSFXCOMPRESSOR_GAIN_MIN = -60 (&HFFFFFFC4)
End Enum

定数

DSFXCOMPRESSOR_GAIN_MAX
最大値。
DSFXCOMPRESSOR_GAIN_MIN
最小値。


CONST_DSFXCOMPRESSOR_PREDELAY

DSFXCOMPRESSOR 型の fPreDelay メンバで使用される。

Enum CONST_DSFXCOMPRESSOR_PREDELAY
    DSFXCOMPRESSOR_PREDELAY_MAX = 4
    DSFXCOMPRESSOR_PREDELAY_MIN = 0
End Enum

定数

DSFXCOMPRESSOR_PREDELAY_MAX
最大値。
DSFXCOMPRESSOR_PREDELAY_MIN
最小値。


CONST_DSFXCOMPRESSOR_RATIO

DSFXCOMPRESSOR 型の fRatio メンバで使用される。

Enum CONST_DSFXCOMPRESSOR_RATIO
    DSFXCOMPRESSOR_RATIO_MAX =  100 (&H64)
    DSFXCOMPRESSOR_RATIO_MIN =    1
End Enum

定数

DSFXCOMPRESSOR_RATIO_MAX
最大値。
DSFXCOMPRESSOR_RATIO_MIN
最小値。


CONST_DSFXCOMPRESSOR_RELEASE

DSFXCOMPRESSOR 型の fRelease メンバで使用される。

Enum CONST_DSFXCOMPRESSOR_RELEASE
    DSFXCOMPRESSOR_RELEASE_MAX = 3000 (&HBB8)
    DSFXCOMPRESSOR_RELEASE_MIN =   50 (&H32)
End Enum

定数

DSFXCOMPRESSOR_RELEASE_MAX
最大値。
DSFXCOMPRESSOR_RELEASE_MIN
最小値。


CONST_DSFXCOMPRESSOR_THRESHOLD

DSFXCOMPRESSOR 型の fThreshold メンバで使用される。

Enum CONST_DSFXCOMPRESSOR_THRESHOLD
    DSFXCOMPRESSOR_THRESHOLD_MAX =   0
    DSFXCOMPRESSOR_THRESHOLD_MIN = -60 (&HFFFFFFC4)
End Enum

定数

DSFXCOMPRESSOR_THRESHOLD_MAX
最大値。
DSFXCOMPRESSOR_THRESHOLD_MIN
最小値。


CONST_DSFXDISTORTION_EDGE

DSFXDISTORTION 型で使用される。

Enum CONST_DSFXDISTORTION_EDGE
    DSFXDISTORTION_EDGE_MAX = 100 (&H64)
    DSFXDISTORTION_EDGE_MIN =   0
End Enum

定数

DSFXDISTORTION_EDGE_MAX
最大値。
DSFXDISTORTION_EDGE_MIN
最小値。


CONST_DSFXDISTORTION_GAIN

DSFXDISTORTION 型で使用される。

Enum CONST_DSFXDISTORTION_GAIN
    DSFXDISTORTION_GAIN_MAX =   0
    DSFXDISTORTION_GAIN_MIN = -60 (&HFFFFFFC4)
End Enum

定数

DSFXDISTORTION_GAIN_MAX
最大値。
DSFXDISTORTION_GAIN_MIN
最小値。


CONST_DSFXDISTORTION_POSTEQBANDWIDTH

DSFXDISTORTION 型で使用される。

Enum CONST_DSFXDISTORTION_POSTEQBANDWIDTH
    DSFXDISTORTION_POSTEQBANDWIDTH_MAX = 8000 (&H1F40)
    DSFXDISTORTION_POSTEQBANDWIDTH_MIN =  100 (&H64)
End Enum

定数

DSFXDISTORTION_POSTEQBANDWIDTH_MAX
最大値。
DSFXDISTORTION_POSTEQBANDWIDTH_MIN
最大値。


CONST_DSFXDISTORTION_POSTEQCENTERFREQUENCY

DSFXDISTORTION 型で使用される。

Enum CONST_DSFXDISTORTION_POSTEQCENTERFREQUENCY
    DSFXDISTORTION_POSTEQCENTERFREQUENCY_MAX = 8000 (&H1F40)
    DSFXDISTORTION_POSTEQCENTERFREQUENCY_MIN = 100 (&H64)
End Enum

定数

DSFXDISTORTION_POSTEQCENTERFREQUENCY_MAX
最大値。
DSFXDISTORTION_POSTEQCENTERFREQUENCY_MIN
最小値。


CONST_DSFXDISTORTION_PRELOWPASSCUTOFF

DSFXDISTORTION 型で使用される。

Enum CONST_DSFXDISTORTION_PRELOWPASSCUTOFF
    DSFXDISTORTION_PRELOWPASSCUTOFF_MAX = 8000 (&H1F40)
    DSFXDISTORTION_PRELOWPASSCUTOFF_MIN =  100 (&H64)
End Enum

定数

DSFXDISTORTION_PRELOWPASSCUTOFF_MAX
最大値。
DSFXDISTORTION_PRELOWPASSCUTOFF_MIN
最小値。


CONST_DSFXGARGLE_RATEHZ

DSFXGARGLE 型で使用される。

Enum CONST_DSFXGARGLE_RATEHZ
    DSFXGARGLE_RATEHZ_MAX = 1000 (&H3E8)
    DSFXGARGLE_RATEHZ_MIN =    1
End Enum

定数

DSFXGARGLE_RATEHZ_MAX
最大値。
DSFXGARGLE_RATEHZ_MIN
最小値。


CONST_DSFXGARGLE_WAVE

DSFXGARGLE 型で使用される。

Enum CONST_DSFXGARGLE_WAVE
    DSFXGARGLE_WAVE_SQUARE   = 1
    DSFXGARGLE_WAVE_TRIANGLE = 0
End Enum

定数

DSFXGARGLE_WAVE_TRIANGLE
三角波。
DSFXGARGLE_WAVE_SQUARE
矩形波。


CONST_DSFXPARAMEQ_BANDWIDTH

DSFXPARAMEQ 型の fBandwidth メンバで使用される。

Enum CONST_DSFXPARAMEQ_BANDWIDTH
    DSFXPARAMEQ_BANDWIDTH_MAX = 36 (&H24)
    DSFXPARAMEQ_BANDWIDTH_MIN =  1
End Enum

定数

DSFXPARAMEQ_BANDWIDTH_MAX
最大値。
DSFXPARAMEQ_BANDWIDTH_MIN
最小値。


CONST_DSFXPARAMEQ_CENTER

DSFXPARAMEQ 型の fCenter メンバで使用される。

Enum CONST_DSFXPARAMEQ_CENTER
    DSFXPARAMEQ_CENTER_MAX = 16000 (&H3E80)
    DSFXPARAMEQ_CENTER_MIN =    80 (&H50)
End Enum

定数

DSFXPARAMEQ_CENTER_MAX
最大値。
DSFXPARAMEQ_CENTER_MIN
最小値。


CONST_DSFXPARAMEQ_GAIN

DSFXPARAMEQ 型の fGain メンバで使用される。

Enum CONST_DSFXPARAMEQ_GAIN
    DSFXPARAMEQ_GAIN_MAX =  15
    DSFXPARAMEQ_GAIN_MIN = -15 (&HFFFFFFF1)
End Enum

定数

DSFXPARAMEQ_GAIN_MAX
最大値。
DSFXPARAMEQ_GAIN_MIN
最小値。


CONST_DSOUND

DirectSound で使用されるさまざまな定数。

Enum
    DS3D_DEFAULTCONEANGLE         = 360 (&H168)
    DS3D_DEFAULTCONEOUTSIDEVOLUME =          0
    DS3D_DEFAULTDISTANCEFACTOR    =          1
    DS3D_DEFAULTDOPPLERFACTOR     =          1
    DS3D_DEFAULTMAXDISTANCE       = 1000000000 (&H3B9ACA00)
    DS3D_DEFAULTMINDISTANCE       =          1
    DS3D_DEFAULTROLLOFFFACTOR     =          1
    DS3D_MAXCONEANGLE             =        360 (&H168)
    DS3D_MAXDISTANCEFACTOR        =         10
    DS3D_MAXDOPPLERFACTOR         =         10
    DS3D_MAXROLLOFFFACTOR         =         10
    DS3D_MINCONEANGLE             =          0
    DS3D_MINDISTANCEFACTOR        =          0
    DS3D_MINDOPPLERFACTOR         =          0
    DS3D_MINROLLOFFFACTOR         =          0
    DSBFREQUENCY_MAX              =     100000 (&H186A0)
    DSBFREQUENCY_MIN              =        100 (&H64)
    DSBFREQUENCY_ORIGINAL         =          0
    DSBPAN_CENTER                 =          0
    DSBPAN_LEFT                   =     -10000 (&HFFFFD8F0)
    DSBPAN_RIGHT                  =      10000 (&H2710)
    DSBPN_OFFSETSTOP              =         -1 (&HFFFFFFFF)
    DSBSIZE_MAX                   =  268435455 (&HFFFFFFF)
    DSBSIZE_MIN                   =          4
    DSBVOLUME_MAX                 =          0
    DSBVOLUME_MIN                 =     -10000 (&HFFFFD8F0)
    WAVE_FORMAT_PCM               =          1
End Enum

定数

DS3D_DEFAULTCONEANGLE = 360 (&H168)
DS3D_DEFAULTCONEOUTSIDEVOLUME
DS3D_DEFAULTDISTANCEFACTOR
DS3D_DEFAULTDOPPLERFACTOR
DS3D_DEFAULTMAXDISTANCE
DS3D_DEFAULTMINDISTANCE
DS3D_DEFAULTROLLOFFFACTOR
DS3D_MAXCONEANGLE
DS3D_MAXDISTANCEFACTOR
DS3D_MAXDOPPLERFACTOR
DS3D_MAXROLLOFFFACTOR
DS3D_MINCONEANGLE
DS3D_MINDISTANCEFACTOR
DS3D_MINDOPPLERFACTOR
DS3D_MINROLLOFFFACTOR
3D バッファ パラメータに設定可能な値およびデフォルト値。
DSBFREQUENCY_MAX
DSBFREQUENCY_MIN
DSBFREQUENCY_ORIGINAL
DSBPAN_CENTER
DSBPAN_LEFT
DSBPAN_RIGHT
DSBPN_OFFSETSTOP
DSBSIZE_MAX
DSBSIZE_MIN
DSBVOLUME_MAX
DSBVOLUME_MIN
バッファ パラメータに設定可能な値およびデフォルト値。
WAVE_FORMAT_PCM
WAVEFORMATEX 型の nFormatTag メンバで使用される。


CONST_DSOUNDERR

DirectMusic のエラー コードを表す。値の一覧については、「DirectSound のエラー コード」を参照すること。


CONST_DSOUNDFX

エフェクト バッファ作成のパラメータの指定および取得に使用される。

Enum CONST_DSOUNDFX
    DSFX_LOCHARDWARE  = 1
    DSFX_LOCSOFTWARE  = 2
    DSFXR_FAILED      = 4
    DSFXR_LOCHARDWARE = 1
    DSFXR_LOCSOFTWARE = 2
    DSFXR_PRESENT     = 0
    DSFXR_UNALLOCATED = 3
    DSFXR_UNKNOWN     = 5
End Enum

定数

DSFX_LOCHARDWARE
DSFX_LOCSOFTWARE
これらのフラグは、再生バッファ エフェクトの作成を制御する。DSEFFECTDESC を参照すること。
DSFXR_FAILED
DSFXR_LOCHARDWARE
DSFXR_LOCSOFTWARE
DSFXR_PRESENT
DSFXR_UNALLOCATED
DSFXR_UNKNOWN
これらの値は、再生バッファ エフェクトの作成に対する結果を表す。「DirectSoundSecondaryBuffer8.AcquireResources」および「DirectSoundSecondaryBuffer8.SetFX」を参照すること。


CONST_DSSCLFLAGS

DirectSound8.SetCooperativeLevel メソッドの level パラメータで使用され、優先レベルを指定する。

Enum CONST_DSSCLFLAGS
    DSSCL_NORMAL       = 1
    DSSCL_PRIORITY     = 2
    DSSCL_WRITEPRIMARY = 4
End Enum

定数

DSSCL_NORMAL
アプリケーションを完全に協調可能なステータスに設定する。このレベルでは最もスムーズなマルチタスキングとリソース共有の動作が得られるが、プライマリ バッファのフォーマットの変更は行えず、出力もデフォルトの 8 ビット フォーマットに限定される。
DSSCL_PRIORITY
アプリケーションを優先レベルに設定する。この協調レベルのアプリケーションは、DirectSoundPrimaryBuffer8.SetFormat メソッドを呼び出すことができる。
DSSCL_WRITEPRIMARY
アプリケーションを最上位の優先レベルに設定する。このアプリケーションはプライマリ サウンド バッファへの書き込みアクセスを保持する。

注意

DSSCL_EXCLUSIVE 協調レベルは、現在サポートされていない。


CONST_DSSPEAKERFLAGS

DirectSound8.GetSpeakerConfig および DirectSound8.SetSpeakerConfig メソッドで使用され、スピーカ構成を指定する。

Enum CONST_DSSPEAKERFLAGS
    DSSPEAKER_GEOMETRY_MAX    = 180 (&HB4)
    DSSPEAKER_GEOMETRY_MIN    =   5
    DSSPEAKER_GEOMETRY_NARROW =  10
    DSSPEAKER_GEOMETRY_WIDE   =  20 (&H14)
    DSSPEAKER_HEADPHONE       =   1
    DSSPEAKER_MONO            =   2
    DSSPEAKER_QUAD            =   3
    DSSPEAKER_STEREO          =   4
    DSSPEAKER_SURROUND        =   5
End Enum

定数

DSSPEAKER_GEOMETRY_MAX
2 つのスピーカはリスナーを中心として 180 度の角度に置かれている。
DSSPEAKER_GEOMETRY_MIN
2 つのスピーカはリスナーを中心として 5 度の角度に置かれている。
DSSPEAKER_GEOMETRY_NARROW
2 つのスピーカはリスナーを中心として 10 度の角度に置かれている。
DSSPEAKER_GEOMETRY_WIDE
2 つのスピーカはリスナーを中心として 20 度の角度に置かれている。
DSSPEAKER_HEADPHONE
スピーカはヘッドホンである。
DSSPEAKER_MONO
スピーカはモノラルである。
DSSPEAKER_QUAD
スピーカは 4 チャンネルである。
DSSPEAKER_STEREO
スピーカはステレオである。
DSSPEAKER_SURROUND
スピーカはサラウンド サウンドである。


CONST_WAVEFORMATFLAGS

DSCCAPS 型の lFormats メンバで使用され、サポートされる標準フォーマットを示す。

Enum CONST_WAVEFORMATFLAGS
    WAVE_FORMAT_1M08 =    1
    WAVE_FORMAT_1M16 =    4
    WAVE_FORMAT_1S08 =    2
    WAVE_FORMAT_1S16 =    8
    WAVE_FORMAT_2M08 =   16 (&H10)
    WAVE_FORMAT_2M16 =   64 (&H40)
    WAVE_FORMAT_2S08 =   32 (&H20)
    WAVE_FORMAT_2S16 =  128 (&H80)
    WAVE_FORMAT_4M08 =  256 (&H100)
    WAVE_FORMAT_4M16 = 1024 (&H400)
    WAVE_FORMAT_4S08 =  512 (&H200)
    WAVE_FORMAT_4S16 = 2048 (&H800)
End Enum

定数

WAVE_FORMAT_1M08
11.025 kHz、モノラル、8 ビット。
WAVE_FORMAT_1M16
11.025 kHz、モノラル、16 ビット。
WAVE_FORMAT_1S08
11.025 kHz、ステレオ、8 ビット。
WAVE_FORMAT_1S16
11.025 kHz、ステレオ、16 ビット。
WAVE_FORMAT_2M08
22.05 kHz、モノラル、8 ビット。
WAVE_FORMAT_2M16
22.05 kHz、モノラル、16 ビット。
WAVE_FORMAT_2S08
22.05 kHz、ステレオ、8 ビット。
WAVE_FORMAT_2S16
22.05 kHz、ステレオ、16 ビット。
WAVE_FORMAT_4M08
44.1 kHz、モノラル、8 ビット。
WAVE_FORMAT_4M16
44.1 kHz、モノラル、16 ビット。
WAVE_FORMAT_4S08
44.1 kHz、ステレオ、8 ビット。
WAVE_FORMAT_4S16
44.1 kHz、ステレオ、16 ビット。


DirectSound のエラー コード

ここでは、メソッドの呼び出しでエラーが発生したときに Err.Number に返される、DirectSound に固有の値を説明する。各メソッドが返す可能性のある特定のコードのリストについては、個別のメソッドの説明を参照すること。これらのリストは必ずしも包括的なものとは限らない。

エラー コードは以下のトピックに示されている。

  • DirectSound エラー コード (値)
  • DirectSound エラー コード (名前)


DirectSound エラー コード (値)

次の表は、値で格納される DirectSound エラー コードを示している。説明については、定数をクリックすること。

16 進数 | 定数
&H00000007 | DSERR_OUTOFMEMORY
&H000001AE | DSERR_NOINTERFACE
&H80004001 | DSERR_UNSUPPORTED
&H80004005 | DSERR_GENERIC
&H80070057 | DSERR_INVALIDPARAM
&H8878000A | DSERR_ALLOCATED
&H8878001E | DSERR_CONTROLUNAVAIL
&H88780032 | DSERR_INVALIDCALL
&H88780046 | DSERR_PRIOLEVELNEEDED
&H88780064 | DSERR_BADFORMAT
&H88780078 | DSERR_NODRIVER
&H88780082 | DSERR_ALREADYINITIALIZED
&H88780096 | DSERR_BUFFERLOST
&H887800A0 | DSERR_OTHERAPPHASPRIO
&H887800AA | DSERR_UNINITIALIZED
&H887810B4 | DSERR_BUFFERTOOSMALL
&H887810BE | DSERR_DS8_REQUIRED
&H88781161 | DSERR_OBJECTNOTFOUND


DirectSound エラー コード (名前)

次のリストは、すべての DirectSound エラー コードを示している。値から定数を確認するには、「DirectSound エラー コード (値)」を参照すること。

DSERR_ALLOCATED
優先レベルなどのリソースがほかの呼び出しによって既に使用中であるため、要求は失敗した。
DSERR_ALREADYINITIALIZED
オブジェクトは既に初期化されている。
DSERR_BADFORMAT
指定したウェーブ フォーマットはサポートされていない。
DSERR_BUFFERLOST
バッファ メモリが失われたため、復元しなければならない。
DSERR_BUFFERTOOSMALL
エフェクト処理をサポートできるほど、バッファが大きくない。
DSERR_CONTROLUNAVAIL
呼び出し元が要求するコントロール (ボリューム、パンなど) は利用できない。
DSERR_DS8_REQUIRED
要求された機能に対して、CLSID_DirectSound8 クラスまたはそれ以降の DirectSound オブジェクトが要求されている。
DSERR_GENERIC
DirectSound サブシステム内で不確定のエラーが発生した。
DSERR_INVALIDCALL
このオブジェクトの現在の状態では、この関数は有効ではない。
DSERR_INVALIDPARAM
無効なパラメータが関数に渡された。
DSERR_NODRIVER
利用可能なサウンド ドライバが存在しない。
DSERR_NOINTERFACE
要求された COM インターフェイスは利用できない。
DSERR_OBJECTNOTFOUND
要求されたオブジェクトが見つからなかった。
DSERR_OTHERAPPHASPRIO
ほかのアプリケーションより高い優先レベルを持っているため、この呼び出しは成功しなかった。
DSERR_OUTOFMEMORY
DirectSound サブシステムは、呼び出し元の要求を完了するための十分なメモリを割り当てられなかった。
DSERR_PRIOLEVELNEEDED
呼び出し元は、関数を成功させるために必要な優先レベルを持っていない。
DSERR_UNINITIALIZED
DirectSound デバイスは初期化されていなかった。
DSERR_UNSUPPORTED
呼び出した関数はこの時点ではサポートされていない。


DirectInput

このセクションでは、Microsoft® DirectX® API (Application Programming Interface) の Microsoft DirectInput® コンポーネントについて説明する。DirectInput API は、キーボード、マウス、ジョイスティック、その他ゲーム コントローラからのデータの処理に使用する。

ドキュメントの概要については、「ロードマップ」を参照すること。


ロードマップ

Microsoft® DirectInput® の使用について、以下のセクションに分けて説明する。このページは、DirectInput 開発者としての経験レベルに応じたドキュメントのガイドとして利用できる。

DirectInput の新機能。Microsoft® DirectX® の今回のバージョンで追加された機能のまとめ。既に Microsoft DirectInput® を使用した経験があり、新機能を利用したい場合は、このセクションを参照する。

DirectInput の概要。DirectInput の機能とその実装手順についての高度な概要。DirectInput を初めて使用するユーザーは、このセクションから読み始めること。

DirectInput について。DirectInput のオブジェクトとクラスについて、そして Microsoft Windows® メッセージ システムとの関係についての概要。DirectInput を初めて使用するユーザーは、このセクションを参照すること。

DirectInput の使い方。API (application programming interface) の説明。このセクションでは、前の 2 つのセクションより詳しい概念的な情報を説明する。また、デバイスの設定、データの取得、フォース フィードバック エフェクトの実装で使用する API 要素についても説明する。初心者の場合は、少なくとも、このセクションの内容をよく理解すること。後で必要なトピックを参照することができる。このセクションは、「DirectInput Visual Basic リファレンス」とあわせて利用する。

プログラミングのヒントとツール。高度なプログラミング関連トピックと、DirectX Software Development Kit (SDK) 付属の DirectInput ツールについての説明。

DirectInput Visual Basic チュートリアル。ほとんどの場合、SDK のサンプルに基づくステップ バイ ステップ方式のチュートリアル。サンプル コードを使うと理解しやすい場合は、「DirectInput の概要」と「DirectInput について」を読んだ後、このチュートリアルに進むのがよい。

DirectInput Visual Basic サンプル。SDK に付属している DirectInput の Visual Basic サンプル アプリケーションへのガイド。DirectInput の使用方法、機能などが説明されている。

DirectInput Visual Basic リファレンス。API のリファレンス情報。クラス、メソッド、型、マクロ、その他要素の詳細を知りたい場合は、このセクションを利用する。


DirectInput の新機能

Microsoft® DirectInput® の新機能は次のとおりである。

アクション マッピング
Microsoft DirectInput for Microsoft DirectX® 8.0 では、アクション マッピングという重要な新機能が導入された。アクション マッピングは、特定のデバイス オブジェクト (特定のボタンや軸) の存在に依存しない、入力アクションと入力デバイスとの間の接続確立を可能にする。アクション マッピングは、入力ループを簡素化し、ゲームにおけるカスタムのゲーム ドライバ、カスタムのデバイス プロファイラ、およびカスタムの環境設定ユーザー インターフェイスの必要性を軽減する。

詳細については、「アクション マッピング」を参照すること。

DirectInput オブジェクトの新機能
DirectInput オブジェクトは DirectInput8 インターフェイスによって表現され、DirectX8.DirectInputCreate メソッドを使って取得される。
新しいキーボード プロパティ
2 つのキーボード プロパティが追加された。ローカライズされたキー名を取得する DIPROP_KEYNAME と、スキャン コードを取得する DIPROP_SCANCODE である。
rglSlider 配列内のジョイスティック スライダ データ
ジョイスティック スライダ データは、DirectX の前のバージョンでは DIJOYSTATE または DIJOYSTATE2 型の Z 軸に割り当てられていたが、今回のバージョンでは同じ型の slider 配列内に格納される。


DirectInput の概要

Microsoft® DirectInput® は、マウス、キーボード、ジョイスティック、その他ゲーム コントローラの入力デバイスに加え、フォース フィードバック (入出力) デバイスもサポートする API である。

このセクションでは、DirectInput の能力とアプリケーションでの設定方法について、簡単な概要を説明する。以下のトピックに分けて、説明する。

  • DirectInput のパワー
  • DirectInput の基礎知識

DirectInput の機能の総合的説明については、「DirectInput について」を参照すること。

DirectInput API (application programming interface) の使用法をステップ バイ ステップ方式で説明するガイドについては、以下のトピックを参照すること。

  • DirectInput の使い方
  • DirectInput Visual Basic チュートリアル


DirectInput のパワー

Microsoft® DirectInput® は、Microsoft Win32® API がサポートしていないデバイスに新しいサービスを提供することに加え、Microsoft Windows® メッセージに依存せずに、ハードウェア ドライバと直接通信することにより、入力データへのアクセスを高速化している。

DirectInput を使うと、アプリケーションがバックグラウンドにある場合でも、入力デバイスに対するアクセス権を取得できる。また、フォース フィードバックのほか、あらゆるタイプの入力デバイスを完全にサポートしている。

アクション マッピングを介して、アプリケーションは、データがどんなデバイスで生成されたかを知らなくても、入力データを取得することができる。

DirectInput の拡張サービスと性能の改善により、DirectInput は、Windows で動作するゲーム、シミュレーション、およびその他のリアルタイム対話型アプリケーションに対する有用なツールとなっている。

DirectInput では、テキスト入力にキーボードを使用したり、移動にマウスを使用するアプリケーションが有利になることはない。詳細については、「Windows との相互作用」を参照すること。


DirectInput の基礎知識

ここでは、Microsoft® DirectInput® の設定法と単純なアプリケーションでの使用に関する概要について説明する。

このステップの詳細と例については、「DirectInput の使い方」と「DirectInput Visual Basic チュートリアル」を参照すること。

注 : DirectInput を理解するには、以下の用語を理解する必要がある。

  • DirectInput オブジェクト : ルートの DirectInput インターフェイス。
  • デバイス : キーボード、マウス、ジョイスティック、その他の入力デバイス。
  • DirectInputDevice オブジェクト : キーボード、マウス、ジョイスティック、その他の入力デバイスを表すコード。
  • デバイス オブジェクト : DirectInput デバイス オブジェクト上のキー、ボタン、トリガなどを表すコード。デバイス オブジェクト インスタンス とも呼ぶ。

以下のステップは、アプリケーションにおいて、どのデバイス オブジェクト (ボタン、軸など) がデータ項目を生成したかを確認するための DirectInput の単純な実装を示している。

  1. DirectInput オブジェクトを作成する。このオブジェクトのメソッドを使用して、デバイスを列挙し、DirectInput デバイス オブジェクトを作成する。
  2. デバイスを列挙する。システム マウスまたはキーボードのみを使用する場合は、このステップは必ずしも必要ではない。ユーザーのシステム上でほかにどんな入力デバイスが使用できるかを確認するには、DirectInput にデバイスを列挙させる。DirectInput は、設定基準と一致するデバイスを発見するたびに、その能力をチェックする機会を提供してくれる。また、そのデバイスを表す DirectInput デバイス オブジェクトを作成するための固有の識別子も取得する。
  3. 使用デバイスごとに DirectInputDevice オブジェクトを作成する。これには、列挙中に取得された固有の識別子が必要となる。システム マウスまたはキーボードについては、標準の GUID を使用できる。
  4. デバイスを設定する。デバイスごとに、まず協調レベルを設定し、他のアプリケーションやシステムとそのデバイスを共有する方法を指定する。また、データ パケット内で、ボタンや軸などそのデバイス オブジェクトを識別するためのデータ形式を設定する。バッファリング データを取得する場合 (ステートではなくイベントを取得する場合) は、バッファ サイズも設定する必要がある。オプションとして、この段階でデバイスに関する情報を取得し、アプリケーションの動作をそれに応じて調整する。また、ジョイスティックの軸によって返される値の範囲などのプロパテイを設定することもできる。
  5. デバイスを取得する。この段階で、DirectInput に対し、デバイスからデータを受け取る準備ができたことを通知する。
  6. データを取得する。一定の間隔で、普通はメッセージ ループまたはレンダリング ループを 1 回繰り返すたびに、各デバイスの現在の状態か前回取得後に発生したイベントの記録のいずれかを取得する。好みに応じて、イベントが発生したら DirectInput から通知させることもできる。
  7. データを処理する。アプリケーションは、ボタンや軸の状態か、キーが押されているか離されているかなどのイベントのいずれかに反応できる。
  8. DirectInput を終了する。終了する前に、アプリケーションはすべてのデバイスの取得を解除して解放し、次に DirectInput オブジェクトを解放しなければならない。

DirectInput を実装する方法は、これだけではない。現在使用されている、または将来使用されるバラエティ豊富な入力デバイスを活用するため、またユーザーの環境設定を簡素化するため、アクション マッピングを使用することができる。

デバイスにアクション マッピングを設定することにより、アプリケーションの各アクションに使用するデバイス オブジェクトを、DirectInput に決めさせることができる。たとえばレーシング ゲームで、スロットルが常に y 軸によって制御されるように指定する代わりに、AXIS_THROTTLE というアクションを作成し、デバイス上で最も適切な軸に DirectInput がアクションを割り当てるようにすることができる。イベントを取得したときは、そのイベントを生成したデバイス オブジェクトではなく、そのイベントに関連付けられているアクションによってイベントを識別する。

詳細については、「アクション マッピング」を参照すること。


DirectInput について

このセクションでは、Microsoft® DirectInput® の基本構造と、Microsoft Windows® メッセージ システムと DirectInput 間の関係について説明する。

  • DirectInput オブジェクト
  • Windows との相互作用

ここで説明する DirectInput の各要素の実装方法については、「DirectInput の使い方」を参照すること。


DirectInput オブジェクト

入力専用の Microsoft® DirectInput® 実装は、アプリケーションが使用している入力デバイスごとに 1 つの DirectInput8 オブジェクトと DirectInputDevice8 オブジェクトで構成される。DirectInputDevice8 オブジェクトは、入力データを取得するのに使用される。

また、すべての使用可能なデバイスは、DirectInput により使用されているかどうかにかかわらず、DirectInputDeviceInstance8 オブジェクトで表現できる。このオブジェクトを使うことで、そのデバイスに関するさまざまな情報を取得できる。

それぞれの DirectInputDevice8 オブジェクトは、マウス、キーボード、またはジョイスティックなどの入力デバイスを表す(DirectInput API では、ジョイスティックという用語には、マウスやキーボード以外のあらゆるゲーム コントローラが含まれる)。タッチパッド付きキーボードなど、実際には異なる種類の入力デバイスを組み合わせた物理デバイスは、2 つまたはそれ以上の DirectInputDevice8 オブジェクトとして表される。フォースフィードバック デバイスは、入力と出力の両方を操作する 1 つのジョイスティック オブジェクトとして表される。

各デバイスは、キー、ボタン、軸などの個別の制御手段またはスイッチであるデバイス オブジェクトを持つ。各デバイス オブジェクトは、DirectInputDeviceObjectInstance クラスのインスタンスにより表現される。このメソッドを使うことで、そのデバイス オブジェクトに関する情報を取得できる (ただし、入力データは常に DirectInputDevice8 で取得する)。

デバイスとデバイス オブジェクトは列挙できる。列挙結果のコレクションは、DirectInput8.GetDIDevices オブジェクトと DirectInputDevice8.GetDeviceObjectsEnum オブジェクトで表される。

フォース フィードバック エフェクトは、DirectInputEffect クラスにより表される。このインターフェイスの各メソッドを使って、エフェクトの生成、変更、開始、および停止を行う。


Windows との相互作用

Microsoft® DirectInput® はデバイス ドライバに直接働きかけて動作するので、Microsoft Windows® のマウス メッセージとキーボード メッセージは抑制または無視される。DirectInput は、コントロール パネルでユーザーが行ったマウスとキーボードの設定も無視する。ただし、ジョイスティックやその他のゲーム コントローラのキャリブレーションの設定は使用する。

DirectInput は、キーボードの文字反復の設定を認識しない。バッファリング データを利用しているときは、DirectInput は、個々のキーの「押し」と「離し」を反復なしの 1 つのイベントとして解釈する。直接データを利用しているときは、DirectInput が関与するのはキーの現在の物理的状態のみであり、Windows で解釈されるキーボード イベントには関与しない。

DirectInput は、文字変換や平行移動を実行しない。たとえば Shift キーは、他のキーの修正子としてではなく、他のキーと同じように処理される。キーは、ユーザーのシステム言語設定に関係なく、同じ識別子を返す。

Windows 2000 では、排他モードでキーボードを取得すると、その後で起動されたどのアプリケーションもキーボード データを取得できなくなる。

DirectInput は直接マウス ドライバに作用するため、ウィンドウ表示アプリケーションに対してマウス データを解釈する Windows サブシステムをバイパスする。Windows カーソルを使用して移動するアプリケーションは、標準の Windows マウス メッセージおよび Microsoft® Win32® 関数を使用する。

排他モードでマウスを使用すると、DirectInput はマウス メッセージを抑制する。その結果、Windows は標準カーソルを表示できなくなる。

DirectInput は加速値やボタン機能の入れ替えなどのコントロール パネルの設定を無視する。しかし、ドライバそのもので設定を認識する。たとえば、ユーザーが 3 つボタンのマウスを持っていて、ドライバ ユーティリティ ソフトウェアを使って中央のボタンにダブルクリックのショートカットを割り当てると、DirectInput は、中央のボタンの 1 回のクリックを主ボタンの 2 回のクリックとして報告する。


DirectInput の使い方

ここでは、Microsoft® DirectInput® の実装について説明する。より幅広い概要については、「DirectInput について」を参照すること。

次のトピックについて解説する。

  • DirectInput の作成
  • DirectInput デバイスの列挙
  • DirectInput デバイス
  • DirectInput デバイス データ
  • アクション マッピング
  • フォース フィードバック


DirectInput の作成

Microsoft® DirectInput アプリケーションでは、必ず最初に DirectInput8 オブジェクトを作成する。これを行うには、DirectX8.DirectInputCreate メソッドを使用する。

単一の DirectInput8 オブジェクトを作成し、アプリケーションが終了するまで解放するべきではない。


DirectInput デバイスの列挙

Microsoft® DirectInput® は、すべての使用可能な入力デバイスをシステムに問い合わせ、それらが接続されているかどうかを判定し、それらのデバイスに関する情報を返すことができる。このプロセスを列挙と呼ぶ。

標準のキーボードやマウス、またはその両方だけをアプリケーションで使っているなら、使用可能な入力デバイスを列挙する必要はない。「DirectInput デバイスの作成」を参照すること。

ほかのすべての入力デバイス、および複数のキーボードまたはマウスを使用するシステムに関しては、DirectInput8.GetDIDevices を呼び出して、使用可能なデバイスのコレクションを作成する。このメソッドは、デバイスのコレクションを表す DirectInputEnumDevices8 オブジェクトを返す。コレクション内の各デバイスは、DirectInputEnumDevices8.GetItem メソッドを使用することにより、DirectInputDeviceInstance8 オブジェクトとして取得できる。次の例は、ゲーム コントローラのコレクションを作成し、それらを lstJoysticks という名前のリスト ボックスに表示する方法を示す。

Dim diDevEnum As DirectInputEnumDevices8

Set diDevEnum = di.GetDIDevices(DI8DEVCLASS_GAMECTRL, DIEDFL_ATTACHEDONLY)

Dim i As Integer
For i = 1 To diDevEnum.GetCount
    Call lstJoysticks.AddItem(diDevEnum.GetItem(i).GetInstanceName)
Next i

非標準デバイスに対して DirectInputDevice8 オブジェクトを作成するには、前もって DirectInputDeviceInstance8.GetGuidInstance を呼び出すことにより、デバイス列挙から少なくともそのデバイスの GUID を取得する必要がある。デバイスを列挙して、特定のタイプやサブタイプを検索したり (DirectInputDeviceInstance8.GetDevType を使用)、ユーザーがゲーム コントローラを選択できるようにリストボックスに代入したりすることもできる。

特定の能力を持つデバイスを検索することもできる。これを行うには、候補となるデバイスのそれぞれについて DirectInputDevice8 オブジェクトを作成し、DirectInputDevice8.GetCapabilities メソッドを使って詳細機能を調査する必要がある。


DirectInput デバイス

ここでは、マウス、キーボード、ジョイスティックなどのデバイスを表すコード オブジェクトについて記述する。以下のトピックについて説明する。

  • デバイスのセットアップ
  • DirectInput デバイスの作成
  • デバイス能力
  • 協調レベル
  • デバイス オブジェクトの列挙
  • デバイス データ形式
  • デバイス プロパティ
  • デバイスの取得

デバイスからのデータの取得および解釈の方法についての情報は、「DirectInput デバイス データ」を参照すること。


デバイスのセットアップ

アプリケーションは、入力が行われるデバイスごとに Microsoft® DirectInput® デバイス オブジェクトを取得しなければならない。そのデバイスが使用できるように、最低限でもデータ形式の設定やデバイスの取得などの準備もしなければならない。ほかにも、デバイスに関する情報の収集やデバイスのプロパティの変更など、独自のタスクを実行することもある。

以下のタスクは、セットアップ手順の一部である。手順の中には必須のものもあれば、デバイスの詳細情報を必要とする場合、あるいはデフォルト値を変更しなければならない場合に限り必要となるものもある。

  1. DirectInput デバイスを作成する (必須)。「DirectInput デバイスの作成」を参照すること。
  2. デバイス能力を取得する (オプション)。
  3. デバイスのキー、ボタンおよび軸を列挙する (オプション)。「デバイス オブジェクトの列挙」を参照すること。
  4. 協調レベルを設定する (推奨)。
  5. デバイス データ形式を設定する (推奨)。
  6. デバイス プロパティを設定する (バッファリング データを取得する予定ならば、少なくともバッファ サイズを設定しなければならない)。
  7. データを読み取る用意ができたら、デバイスを取得する (必須)。「デバイスの取得」を参照すること。


DirectInput デバイスの作成

デバイスから入力データを取得するには、まずそのデバイスを表すオブジェクトを作成しなければならない。

DirectInput8.CreateDevice メソッドを使って、DirectInputDevice8 オブジェクトを取得する。その後、このインターフェイスのメソッドを使って、デバイスの操作とデータの取得を行う。

次のコードは、キーボード デバイスを作成する例である。di は DirectInput8 オブジェクトである。

Dim diDev As DirectInputDevice
Set diDev = di.CreateDevice("GUID_SysKeyboard")

パラメータは GUID のエイリアスであり、インターフェイスの作成対象デバイスのインスタンスを識別する。Microsoft® DirectInput® には、事前定義された 2 つの GUID (GUID_SysMouse および GUID_SysKeyboard) があり、それぞれシステム マウスとシステム キーボードを表す。これらの識別子を CreateDevice メソッドに渡すことができる。

注 : コンピュータに 2 つ以上のマウスがある場合は、すべてのマウスが結合されてシステムデバイスを形成する。キーボードについても同様である。

システム マウスやシステム キーボード以外のデバイスの場合は、DirectInputDeviceInstance8.GetGuidInstance から取得したデバイスのインスタンス GUID を使用する。1 つのデバイスに対するインスタンス GUID は常に同一である。列挙したリストからユーザーに 1 つのデバイスを選択させ、その GUID を構成ファイルに保存しておくと、後のセッションでその GUID を再び使用することができる。

次のサンプル コードは、アプリケーションがデバイスを列挙し、適切なデバイス diDevInstance を見つけたことを前提としている。このデバイスを DirectInputDevice として作成する。

Dim guid As String
guid = diDevInstance.GetGuidInstance
Set diDev = di.CreateDevice(guid)

DirectInputDeviceInstance8 オブジェクトの取得方法については、「DirectInput デバイスの列挙」を参照すること。


デバイス能力

デバイスからの入力を要求する前に、ユーザーがその能力をある程度知っておく必要がある。ジョイスティックに視点ハットが付いているか。マウスはユーザーのマシンに現在アタッチされているか。

そうした疑問点は、DirectInputDevice8.GetCapabilities メソッドを呼び出すことにより解決することができる。このメソッドは、能力に関するデータを DIDEVCAPS 型に返す。

以下のコードは、マウスがアタッチされているかどうか、およびマウスが第 3 軸 (通常は、ホイール) を持っているかどうかをチェックする例である。

' diMouse は、有効な DirectInputDevice オブジェクトである。

Dim WheelAvailable As Boolean
Dim dicaps as DIDEVCAPS

Call diDev.GetCapabilities(dicaps)
WheelAvailable = ((dicaps.lFlags And DIDC_ATTACHED) _
        And (dicaps.lAxes > 2))

あるボタンまたは軸が存在するかどうかをチェックするもう 1 つの方法は、そのオブジェクトに対して DirectInputDevice8.GetObjectInfo を呼び出すことである。その呼び出しに対し DIERR_NOTFOUND が返ってきた場合、オブジェクトは存在しない。以下のコードでは、第 3 軸ではないにしても z 軸が存在するかどうかを判断する。

Dim didoi As DirectInputDeviceObjectInstance
On Error GoTo NOTFOUND
Set didoi = diDev.GetObjectInfo(DIMOFS_Z, DIPH_BYOFFSET)
On Error GoTo 0
.
.
.
NOTFOUND:
If Err.Number = DIERR_NOTFOUND Then
 MsgBox "No z-axis found."
End If


協調レベル

デバイスの協調レベルは、アプリケーション間および Microsoft® Windows® システムでデバイスを共有する方法を定義する。以下の例のように、協調レベルを設定するには DirectInputDevice8.SetCooperativeLevel メソッドを使用する。

' hwnd は、最上位ウィンドウのハンドルである。
Call diDevice.SetCooperativeLevel(hWnd,
        DISCL_NONEXCLUSIVE Or DISCL_FOREGROUND)

パラメータは、デバイスに関連する最上位ウィンドウ (一般的には、アプリケーション ウィンドウ) のハンドルと、1 つまたは複数のフラグである。

注 : フォームの hWnd プロパティは、そのフォームが表示されるまで有効にならない。アプリケーションのメイン フォームの Load メソッドで Microsoft® DirectInput® デバイスを初期化している場合、協調レベルを設定する前に、Show メソッドを呼び出す必要がある。

DirectInput にはデフォルト設定が用意されているが、協調レベルは、明示的に設定しなければならない。これは、DirectInput にウィンドウのハンドルを与えるための唯一の方法だからである。このハンドルがないと、DirectInput は、ジョイスティックの再キャリブレーションなど、ウィンドウ メッセージが必要な状況で反応することができなくなる。

有効なフラグの組み合わせを以下の表に示す。

フラグ | メモ
DISCL_NONEXCLUSIVE DISCL_BACKGROUND | デフォルト設定
DISCL_NONEXCLUSIVE DISCL_FOREGROUND |
DISCL_EXCLUSIVE DISCL_FOREGROUND |
DISCL_EXCLUSIVE DISCL_BACKGROUND | キーボードまたはマウスには無効

キーボードの場合は、DISCL_NOWINKEY と DISCL_NONEXCLUSIVE を同時に使用することもできる。このフラグで Windows キーを無効にすることにより、ユーザーは不注意でアプリケーションを終了することがなくなる。排他モードでは、Windows キーは常に無効である。

注 : Windows キーは、アプリケーションの協調レベルで排他協調レベルを通して受動的に、または DISCL_NOWINKEY フラグを使って能動的に無効にする場合でも、デフォルトのアクション マッピング UI が表示されている間はアクティブになる。

協調レベルには 2 つの構成要素がある。デバイスをフォアグラウンドまたはバックグラウンドで使用するか、および排他または非排他に使用するかである。

フォアグラウンドとバックグラウンド

フォアグラウンド協調レベルは、アプリケーションがフォアグラウンドにある場合、すなわち、入力フォーカスを持つ場合に限り、入力デバイスが使用可能になることを意味する。アプリケーションがバックグラウンドに移ると、入力デバイスは自動的に解放されるか使用不可になる。

バックグラウンド協調レベルとは、実際には「フォアグラウンドとバックグラウンド」のことである。バックグラウンド協調レベルのデバイスは、アプリケーションからいつでも取得して使用できる。

通常は、フォアグラウンド アクセス権だけで十分なはずである。というのも、大半のアプリケーションにとって、ほかのプログラムがフォアグラウンドにある場合に発生する入力に応答するようには設計されていないからである。

アプリケーションの開発中に、条件付きコンパイルを使って、デバッグ用にバックグラウンド協調レベルを設定することは有用である。これにより、アプリケーションは、デバッグ環境への切り替えでバックグラウンドに移動するたびに、デバイスへのアクセスを失うことがなくなる。

排他と非排他

多くの場合、あるアプリケーションがデバイスを排他レベルで使用しているからといって、ほかのアプリケーションが同じデバイスからデータを取得できないということにはならない。「排他レベルで使用」とは、ほかのアプリケーションが同じデバイスを排他には取得できないということを意味する。

たとえばあるミュージック プレーヤー アプリケーションの場合、アプリケーションはバックグラウンドにあっても、ハンドヘルドのリモート コントロール デバイスから入力を受け付ける。ここで、同じリモート コントロール デバイスからの信号に応答して、映画を再生するアプリケーションを実行するとしよう。ユーザーが [Play] を押したら何が起こるだろうか。両方のプログラムが再生を開始することになる。このような結果をユーザーが望んでいるとは思えない。そうならないようにするには、各アプリケーションに DISCL_EXCLUSIVE フラグを設定し、一度にどちらかのプログラムしか実行できないようにする必要がある。

フォース フィードバック エフェクトを利用するには、アプリケーションはデバイスへの排他アクセスができなければならない。

Windows 自体には、マウスへの排他アクセスが必要である。なぜなら、アクティブでないウィンドウ上でのクリックなどのマウス イベントを使って、アプリケーションにデバイスを強制解放させることが可能であり、そのことが、入力バッファからのデータの喪失など、潜在的に有害な結果を生む可能性があるからである。このため、あるアプリケーションが DirectInput8.CreateDevice に GUID_SysMouseを渡して作成されたシステム マウスに対する排他アクセス権を持っていると、Windows には一切のアクセスが許されず、マウス メッセージは生成されない。さらなる副作用として、カーソルが消えることもある。

あるアプリケーションがキーボードに対する排他アクセス権を持っている場合、DirectInput は一切のキーボード メッセージを抑制する。ただし、Ctrl+Alt+Del キーおよび Windows 95 や Windows 98 での Alt+Tab キーは使用できる。Windows 2000 では、排他モードの DirectInput アプリケーションに続いて起動されるアプリケーションは、キーボード データを取得できない。


デバイス オブジェクトの列挙

デバイス上でどのボタンまたは軸が使用可能であるかを、アプリケーションが確認しなければならない場合がある。この確認を行うには、デバイスを列挙する場合とほぼ同じ方法でデバイス オブジェクトを列挙する。

注 : デバイス ドライバによる制約のため、キーボードのキーおよびインジケータ ライトの列挙は信頼できない。オブジェクトが存在するかのような偽りの報告が行われる場合がある。使用可能なキーに関する基本的情報は、デバイスのサブタイプから取得できるが、メニュー キーなどの追加オブジェクトが使用可能かどうかを判定するには、ユーザーに入力を求める以外、方法はない。

DirectInputDevice8.GetDeviceObjectsEnum を呼び出すことで、デバイス オブジェクトを列挙する。これにより、要求したパラメータに一致する使用可能なデバイス オブジェクトのコレクションを表す DirectInputEnumDeviceObjects クラスのインスタンスが返される。

以下のコードは、デバイス上の軸を列挙する例である。

' diDev は DirectInputDevice オブジェクトである。

Dim diEnumObjects As DirectInputEnumDeviceObjects
Set diEnumObjects = diDev.GetDeviceObjectsEnum(DIDFT_AXIS)

パラメータは、列挙の中に含めるオブジェクトのタイプ (複数可) を示すフラグ (この例では 1 つ) である。

注 : CONST_DIDFTFLAGS フラグの一部は、ほかのフラグを組み合わせたものである。たとえば、DIDFT_AXIS は、DIDFT_ABSAXIS OR DIDFT_RELAXIS と同等である。

特定のデバイス オブジェクトに関する情報を取得するには、DirectInputDeviceObjectInstance オブジェクトの各メソッドを呼び出す。このオブジェクトは、DirectInputEnumDeviceObjects.GetItem を呼び出すことで取得される。利用可能なデバイスの情報には、デバイスの名前、タイプ、およびデータ構造体内でのオフセットなどがある。

以下のコードは、前例で列挙された軸の名前をリストする例である。

Dim diDevObjInstance As DirectInputDeviceObjectInstance
Dim i As Integer
For i = 1 To diEnumObjects.GetCount
  Set diDevObjInstance = diEnumObjects.GetItem(i)
  Call List1.AddItem(diDevObjInstance.GetName)
Next i


デバイス データ形式

アクション マッピングを使用していない場合、デバイスのデータ形式の設定は、デバイス取得およびデバイス使用を始める前に行う基本的な手順である。デバイスから直接データ (状態データ) を取得することを目的としていない場合でも、データ形式を設定しなければならない。Microsoft® DirectInput® では多くのメソッドでデータ形式を使用し、特定のデバイス オブジェクトを識別する。

デバイス オブジェクトが使用するデバイスとデータ配列の方法は、DirectInputDevice8.SetCommonDataFormat メソッドと DirectInputDevice8.SetDataFormat メソッドが Microsoft® DirectInput® に対して指示する。

マウス、キーボード、および DIJOYSTATE 型または DIJOYSTATE2 型で記述できる入力データを持つその他のゲーム コントローラなど、標準デバイスの場合、SetCommonDataFormat メソッドを呼び出して、CONST_DICOMMONDATAFORMATS 列挙から定数を渡すことにより、データ形式を設定できる。ほとんどのアプリケーションにとって、共通のデータ形式を使用することが好ましい。

特殊デバイスの場合は、データ形式の記述を SetDataFormat メソッドに渡す必要がある。以下のコードは、2 つの軸を持ちボタンを持たないデバイスに、データ形式を設定する例である。どちらの軸も、データとして Long を要求する。

Dim dx As New DirectX8
Dim di As DirectInput8
Dim did As DirectInputDevice8
Dim fD As DIDATAFORMAT
Dim fDA(1) As DIOBJECTDATAFORMAT

Private Sub Form_Load()
    Set di = dx.DirectInputCreate()

    Set did = di.CreateDevice("GUID_SysMouse")

    fDA(0).lFlags = DIDOI_POLLED
    fDA(0).lOfs = 0
    fDA(0).lType = DIDFT_RELAXIS
    fDA(0).strGuid = "GUID_XAxis"

    fDA(1).lFlags = DIDOI_POLLED
    fDA(1).lOfs = 4
    fDA(1).lType = DIDFT_RELAXIS
    fDA(1).strGuid = "GUID_YAxis"

    fD.dataSize = 8
    fD.lFlags = DIDF_RELAXIS
    fD.lObjSize = 4
    fD.numObjs = 2

    did.SetDataFormat fD, fDA()

End Sub


デバイス プロパティ

Microsoft® DirectInput® デバイスのプロパティには、データ バッファのサイズ、軸が返す値の範囲と細分性、軸データが相対か絶対か、およびジョイスティックの物理的位置と報告データ間の関係に影響するジョイスティック軸のデッド ゾーンと飽和がある。特殊デバイスは、これ以外のプロパティを持つこともある。DirectInput によって定義されたプロパティのリストについては、「DirectInputDevice8.GetProperty」を参照すること。

1 つの例外 (フォース フィードバック デバイスのゲイン プロパティ) を除いて、プロパティは、デバイスが解放された状態にある場合に限り変更することができる。

DirectInputDevice8.SetProperty メソッドおよび DirectInputDevice8.GetProperty メソッドは、2 つのパラメータを取る。設定するプロパティを識別する文字列形式の GUID エイリアスと、Any 型のデータである。このデータは、実際には次のいずれか 1 つの型で渡される。

  • DIPROPLONG は、バッファ サイズなど単一の値を要求するプロパティに対して使用される。このプロパティ データは、単一の Long 値で構成される。
  • DIPROPRANGE はプロパティ範囲に対するもので、2 つの値 (最大値と最小値) を要求する。このプロパティ データは、2 つの Long データ メンバで構成される。

SetProperty の場合、プロパティ構造体のデータ メンバは、プログラマが設定する値である。GetProperty の場合は、現在の値がデータ メンバに返される。

実際のプロパティ データに加えて、これら 2 つの型には、lHow および lObj の 2 つのメンバが含まれる。

lHow と lObj の値は連係して機能する。lHow は、プロパティを設定または取得するデバイス オブジェクトを識別するのに使用されるシステムを表し、lObj はデバイス オブジェクトを識別する。

lHow が DIPH_BYID である場合、デバイス オブジェクトは、lObj の一意な数値識別子で表される。この ID は、デバイス オブジェクトを列挙した後に、DirectInputDeviceObjectInstance.GetType により返される値から抽出できる

ほとんどのアプリケーションの場合、デバイス オブジェクトを識別する方法として比較的容易なのは、DirectInputDevice8.SetCommonDataFormat または DirectInputDevice8.SetDataFormat で確立されるデータ構造体内のオフセットを使用する方法である。この場合、lHow は DIPH_BYOFFSET であり、lObj はバイト単位のオフセットである。キーボード、マウス、および DIJOYSTATE または DIJOYSTATE2 型のデータを受け取ることができる任意のゲーム コントローラの場合、デバイス オブジェクトは事前定義された定数で識別できる。詳細については、「CONST_DIKEYFLAGS」、「CONST_DIMOUSEOFS」、および 「CONST_DIJOYSTICKOFS」を参照すること。

lHow メンバも DIPH_DEVICE を含むことができる。つまり、プロパティの所属先は単一のデバイス オブジェクトではなく、そのデバイス全体である。バッファ サイズはそのようなプロパティの一例である。lHow が DIPH_DEVICE であれば、lObj はゼロである。

SetProperty および GetProperty に渡されるプロパティを識別するために、以下の文字列が使用される。詳細については、「DirectInputDevice8.GetProperty」を参照すること。

  • DIPROP_AXISMODE。「相対座標と絶対座標」も参照すること。
  • DIPROP_BUFFERSIZE。「バッファリング データと直接データ」も参照すること。
  • DIPROP_DEADZONE
  • DIPROP_GRANULARITY
  • DIPROP_RANGE
  • DIPROP_SATURATION

デッド ゾーン、範囲、および飽和値の詳細については、「ジョイスティック軸データの解釈」を参照すること。

以下のコードは、デバイスのバッファ サイズを設定する例である。

' diDev は、データ形式を設定済みの DirectInputDevice である。

Dim diProp As DIPROPLONG
diProp.lHow = DIPH_DEVICE
diProp.lObj = 0
diProp.lData = 10
Call diDev.SetProperty("DIPROP_BUFFERSIZE", diProp)


デバイスの取得

Microsoft® DirectInput® デバイスの取得とは、アプリケーションにデバイスへのアクセスをさせることである。デバイスが取得されている限り、DirectInput は、アプリケーションがデバイスのデータを使用できるようにする。デバイスが取得されていない場合、デバイスの特性に対する操作はできるが、データは一切取得できない。

取得は永続するものではない。アプリケーションは、デバイスを何回でも取得し、解放することがある。

協調レベルによっては、アプリケーションがバックグラウンドに移行すると必ず自動的にデバイスが解放されることがある。マウスの場合、ユーザーがメニューをクリックすると自動的に解放される。クリックした時点で Microsoft Windows® がデバイスの制御を引き継ぐからである。

デバイス プロパティの変更に先立って、そのデバイスを解放する必要がある。唯一の例外として、フォース フィードバック デバイスは、取得状態にあってもゲインを変更できる。

取得の仕組みが必要な理由は、次の 2 つである。

第 1 に、DirectInput は、デバイスからのデータの流れがシステムにより中断されたときには、アプリケーションに通知できなければならない。たとえば、ユーザーが Alt+Tab を使用して別のアプリケーションに切り替え、切り替え後のアプリケーションで入力デバイスを使用した場合に、元のアプリケーションは、入力デバイスがもはや自身に属さず、バッファ状態が変化した可能性があることを知る必要がある。DISCL_FOREGROUND 協調レベルでのアプリケーションを観察してみよう。ユーザーが Shift キーを押しながら別のアプリケーションに切り替える。その後、ユーザーは Shift キーを離し、元のアプリケーションに戻る。元のアプリケーションからみれば、Shift キーは依然として押されている状態である。取得の仕組みでは、元のアプリケーションに入力が終了したことを通知して、この状態から回復させることができる。

第 2 に、アプリケーションがデバイスのプロパティを変更できるので、保護がなければユーザーがデータを取得しようとするたびに、DirectInput がプロパティをチェックしなければならなくなる。これは、かなり非効率であろう。さらに悪いことには、バッファ サイズを変更している最中に、データ バッファにアクセスするハードウェア割り込みなど、事故が発生する可能性がある。そうした理由で、DirectInput は、プロパティを変更する前に、アプリケーションに対してデバイスを解放するように要求する。デバイスを再取得すると、DirectInput はプロパティを確認して、デバイスからアプリケーションへの最適なデータ転送の方法を決定する。この処理は一度しか行われないので、データ取得の各メソッドを非常に高速にすることができる。

特に排他協調レベルを設定した場合は、アプリケーションがデバイスを不意に解放する場合もあるので、アプリケーションが確実に取得状態を追跡するようにする。データを取得しようとした後で、DIERR_INPUTLOST エラーが発生したかどうかをチェックするのも 1 つの方法である。このエラーが発生していると、デバイスが解放されていたことがわかる。アプリケーションがイベント通知に応じて入力を取得している場合、取得が喪失すると、イベントが信号を発する。

排他モードでデバイスを管理する方法の詳細については、「ScrawlB サンプル」を参照すること。

取得済みのデバイスを再取得しようとしても、害はまったくない。Acquire に対する冗長な呼び出しは無視され、デバイスは常時 Unacquire を 1 回呼び出すことで解放することができる。

Windows は、アプリケーションがマウスを排他モードで使用しているときは、マウスにアクセスしない。Windows にマウスを取得させたければ、マウスを解放しなければならない。ScrawlB サンプルでは、右ボタンのクリックに反応するために、マウスを解放し、Windows カーソルを同じ点に表示し、ショートカット メニューを表示し、メニュー選択が行われるまで Windows が入力を処理するようにしている。


DirectInput デバイス データ

ここでは、Microsoft® DirectInput® デバイス データの取得に関する基本的な考え方をいくつか説明する。

  • バッファリング データと直接データ
  • タイム スタンプとシーケンス番号
  • ポーリングとイベント通知
  • 相対座標と絶対座標

出力データ、マウス、キーボードおよびジョイスティック入力データの特定事項については、以下のトピックで詳述する。

  • マウス データ
  • キーボード データ
  • ジョイスティック データ
  • データ出力

DirectInput では、デバイスから取得したデータを識別する 2 つの仕組みを提供する。従来の仕組みを使って、アプリケーションは、マウスの x 軸またはキーボードの F1 キーなどの特定のデバイス オブジェクトから入力されるデータを識別する。Microsoft DirectX® 8.0 以降の新しいシステムでは、DirectInput はアプリケーションが定義した値 (たとえば、移動やシューティングなど、特定のゲーム アクションの識別子) を最も適切な使用可能デバイス オブジェクトに関連付ける。データが取得されると、アプリケーションは、データが入力された実際のデバイスまたはデバイス オブジェクトとの関連を持たない。そのデータの意義に対してのみ動作する。

このセクションで説明する情報の大部分は、両方のメカニズムに適用される。デバイス データの新しい識別法の詳細については、「アクション マッピング」を参照すること。


バッファリング データと直接データ

Microsoft® DirectInput® は、バッファリング データと直接データの 2 種類のデータを供給する。バッファリング データは、アプリケーションが取得するまで格納されているイベントのレコードである。直接データは、デバイスの現在の状態のスナップショットである。

直接データは、デバイスの現在の状態だけに関心のあるアプリケーションで使用することが考えられる。たとえば、ジョイスティックの現在位置と、1 つ以上のボタンの状態に反応するフライト コンバット シミュレーションなどである。バッファリング データは、状態よりもイベントを重要視する場合に選択するとよい。たとえば、マウスの動きやボタンのクリックに反応するアプリケーションなどである。両方のタイプのデータを使用することもできる。たとえば、ジョイスティック軸では直接データを取得して、ボタンではバッファリング データを取得する場合などである。

注 : アクション マッピングを使用する場合、バッッファリング データ パケットには入力に関するアプリケーション定義データが含まれるため、バッファリング データを取得する必要がある。バッファリング データ パケットでは状態ではなくイベントが報告されるため、このデータを取得するには絶対軸の位置を追跡しなければならない。

アプリケーションは、以下のメソッドのいずれかを呼び出すことで、直接データを取得する。

  • DirectInputDevice8.GetDeviceStateKeyboard。DIKEYBOARDSTATE 型のデータを取得するデバイスの場合 (これ以下の 3 つのメソッドについては、DirectInputDevice8.SetCommonDataFormat を使ってデータ形式を設定する必要がある)。
  • DirectInputDevice8.GetDeviceStateMouse。DIMOUSESTATE 型のデータを取得するデバイスの場合。
  • DirectInputDevice8.GetDeviceStateMouse2。DIMOUSESTATE2 型のデータを取得するデバイスの場合。
  • DirectInputDevice8.GetDeviceStateJoystick。DIJOYSTATE 型のデータを取得するデバイスの場合。
  • DirectInputDevice8.GetDeviceStateJoystick2。DIJOYSTATE2 型のデータを取得するデバイスの場合。
  • DirectInputDevice8.GetDeviceState。DirectInputDevice8.SetDataFormat を使ってカスタム データ形式を設定し、使用するデバイスの場合。

名前が表すとおり、これらのメソッドはデバイスの現在の状態を返す。たとえば、各ボタンがアップ状態か、ダウン状態か、などである。このメソッドは、現在の状態と以前の状態を比較して得られる暗黙の情報を除いて、最後の呼び出し以降にデバイスに起きたイベントに関するデータは、まったく提供しない。たとえば、前回の呼び出し以降にユーザーがボタンを押して離した場合、今回の呼び出しではそれらの入力情報はアプリケーションには伝えられない。他方、ボタンを押したままにすると、メソッドは、ユーザーがボタンを離すまで「ボタン ダウン」を報告し続ける。

このデバイス状態の報告は、Click や Keydown のような一度限りのイベントによる Microsoft Visual Basic® のイベント報告とは異なっている。GetDeviceState メソッドのいずれかを使用してデバイスをポーリングする場合には、ボタン クリック、ダブルクリック、または単一のキー ストロークの区別をプログラムで判断しなければならず、また、アプリケーションがボタン ダウン状態またはキー ダウン状態に対し、不適切なタイミングで応答し続けることのないように適切に処理しなければならない。

バッファリング データの場合、イベントは、プログラムが処理を開始できる状態になるまで格納されている。ボタンやキーが押されたり、軸が移動されたりするたびに、そのイベントに対する情報がバッファ中の DIDEVICEOBJECTDATA 型に置かれる。アプリケーションがバッファを読み取るには、DirectInputDevice8.GetDeviceData を呼び出す。一度に任意の数の項目を読み出すことができる。

項目を読み出すと、通常は、バッファからその項目が消去されるが、DIGDD_PEEK フラグを設定すると、削除せずに取得することも選択できる。

バッファリング データを取得するには、まず DirectInputDevice8.SetProperty メソッドでバッファ サイズを設定する必要がある (「デバイス プロパティ」を参照すること)。バッファ サイズの設定は、デバイスを最初に取得する前に行う。効率上の理由から、デフォルトのバッファ サイズはゼロである。この値を変更しない限り、バッファリング データを取得することはできない。バッファ サイズはバイト単位ではなく、デバイスのタイプに対応したデータの項目単位でカウントされる。

GetDeviceData の戻り値は、バッファから取得された項目数を示している。バッファがオーバーフローした場合、データは返されず、GetDeviceData はエラーを発生する。このエラーにより、アプリケーションが捕捉される。

注 : アナログ ジョイスティックなど、割り込みを生成しないデバイスの場合、DirectInputDevice8.Poll メソッドを呼び出すまで、DirectInput はいかなるデータも取得しない。詳細については、「ポーリングとイベント通知」を参照すること。

参照

  • タイム スタンプとシーケンス番号
  • マウス データ
  • キーボード データ
  • ジョイスティック データ


タイム スタンプとシーケンス番号

バッファリングされている Microsoft® DirectInput® 入力データの場合 (「バッファリング データと直接データ」を参照)、各 DIDEVICEOBJECTDATA 型には、イベントのタイプとそれに関連するデバイス オブジェクトだけでなく、タイム スタンプとシーケンス番号も格納される。

lTimeStamp メンバは、イベントが発生したときのシステム時間をミリ秒単位で格納する。これは、Microsoft Win32® GetTickCount 関数によって返される値と同じか、より精度が高い値である。

lSequence メンバは、DirectInput が割り当てたシーケンス番号を格納する。DirectInput システムは、単一のシーケンス カウンタを保持している。このカウンタは、任意のデバイスで、バッファリングされるイベントが発生するたびに随時増加する。(マウスの斜めの動きなど、同一デバイス上で同時に発生したイベントは、1 回だけカウントが増加する)。この番号を使って、異なるデバイスから発生するイベントを比較し、どちらが先かを確認することができる。

注 イベントは、常に、発生時間順にバッファに入れられるので、単一デバイスからのイベントを単に順序付けするだけなら、シーケンス番号をチェックする必要はない。


ポーリングとイベント通知

入力データが発生しているかどうかを確認するには、ポーリングとイベント通知という 2 つの方法がある。

デバイスのポーリングとは、デバイス オブジェクトの現在の状態を定期的に取得すること、またはイベント バッファの内容をチェックすることを意味する。ポーリングが使用されるのは通常、決してアイドルになることがなく、常にゲームの世界を更新、レンダリングするリアルタイム ゲームである。

ポーリング

Microsoft® Visual Basic® アプリケーションでは、ポーリングは通常、Sub Main プロシージャ内で行われる。

ジョイスティックやほかのゲームデバイス、またはこれらのデバイス上のオブジェクトのうちいくつかは、DirectInputDevice8.Poll メソッドを呼び出すまで、ハードウェア割り込みを生成せず、いかなるデータも返さず、いかなるイベントも送信しない (このようなバックグラウンドでのポーリングを、ここで説明するアプリケーション ポーリングと混同しないこと。Poll メソッドは、データを一切取得しないが、データを使用可能にすることがある)。

データを取得しようとするたびに Poll メソッドを呼び出す必要があるかどうかを調べるには、まずデバイスのデータ形式を設定し、次に DirectInputDevice8.GetCapabilities メソッドを呼び出して、DIDEVCAPS 型の DIDC_POLLEDDATAFORMAT フラグをチェックする。

DIDC_POLLEDDATAFORMAT フラグと DIDC_POLLEDDEVICE フラグを混同しないこと。後者は、デバイス上のオブジェクトのどれかがポーリングを必要としているときに設定されるフラグである。次に、DirectInputDevice8.GetObjectInfo メソッドを呼び出して DirectInputDeviceObjectInstance オブジェクトを取得し、DirectInputDeviceObjectInstance.GetFlags により返される値中の DIDOI_POLLED フラグをチェックすると、ポーリングを必要としているのが特定のオブジェクトであるかどうかを見分けることができる。

DIDC_POLLEDDEVICE フラグはデバイスの最悪の状態を表すのであって、デバイスの実際の状態を表すわけではない。たとえば、ソフトウェア解像度調節付きの HID マウスでは、解像度情報を読み取るためにポーリングを要求するので、DIDC_POLLEDDEVICE フラグが設定される。デバイスの標準ボタンと軸データだけを取得したい場合は、このような条件のもとでデバイスをポーリングする必要はない。ただし、任意の入力デバイスに対して Poll メソッドを読み出しても害はない。この呼び出しが不要なときは、何のエフェクトも持たずにすぐに終了する。

イベント通知

イベント通知は、ScrawlB サンプルのように、何もしないで入力を待つようなアプリケーションに適している。

イベント通知を使用するには、データを取得するフォームまたはモジュールに DirectXEvent8 を実装する。次に、DirectX8.CreateEvent を使ってイベント ハンドルを作成し、このハンドルを DirectInputDevice8.SetEventNotification に渡す。これで、デバイスで入力イベントが発生すると必ず DirectXEvent8.DXCallback メソッドが呼び出され、Sub Main 内と同様に、このメソッドの実装内で、デバイスの状態またはバッファリング データのどちらかを取得できる。


相対座標と絶対座標

軸座標は、相対値として返される場合もある。すなわち、アプリケーションが前回デバイスの状態を取得してからの変化量、バッファリング入力の場合は、直前の項目がバッファに入れられてからの変化量である。

絶対軸座標とは、デバイスの取得以来、システムが返したすべての相対座標の連続合計のことである。すなわち、ある固定点に対する軸の位置を示す。

デフォルトでは、マウスの軸は相対座標であり、ジョイスティック軸は絶対座標で報告される。プロパティを設定することで、デバイスの座標システムを変更できる。詳細については、「デバイス プロパティ」を参照すること。


マウス データ

データを取得するようにマウス デバイスを設定するには、まずパラメータに DIFORMAT_MOUSE を指定して DirectInputDevice8.SetCommonDataFormat メソッドを呼び出す。

フルスクリーン アプリケーションの性能を最大にするには、協調レベルに DISCL_EXCLUSIVE | DISCL_FOREGROUND を設定する。排他を設定すると、Microsoft® Windows® カーソルが消失することに注意すること。DISCL_FOREGROUND を設定すると、Microsoft Visual Basic® 開発環境に切り替えたときに、アプリケーションがマウスへのアクセス権を失う。DISCL_BACKGROUND に変更すると、アプリケーションのパフォーマンスは犠牲になるが、アプリケーションのデバッグをより容易に行うことができるようになる。

以下のトピックでは、マウスの直接データとバッファリング データの取得と解釈について詳細に説明する。

  • マウスの直接データ
  • マウスのバッファリング データ
  • マウス軸データの解釈
  • 消失したマウス入力の確認

参照

デバイス データ形式、協調レベル


マウスの直接データ

マウスの現在の状態を取得するには、DIMOUSESTATE または DIMOUSESTATE2 型を指定して DirectInputDevice8.GetDeviceStateMouse または DirectInputDevice8.GetDeviceStateMouse2 を呼び出す。この型に返されるマウス状態には、軸データおよび各ボタンの状態が含まれる。

DIMOUSESTATE および DIMOUSESTATE2 型の x、y、z の各メンバは、軸座標を保持する (「マウス軸データの解釈」を参照すること)。buttons メンバは、バイト配列である。各ボタンに 1 要素が対応する。一般的に、配列の 1 番目の要素が左ボタン、2 番目が右ボタン、3 番目が中央ボタンである。上位ビットは、ボタンがダウン状態の場合にセットされ、ボタンがアップ状態または存在しない場合に消去される。

参照

バッファリング データと直接データ


マウスのバッファリング データ

マウスからバッファリング データを取得するには、バッファ サイズを設定しなければならない (「デバイス プロパティ」を参照すること)。バッファのデフォルト サイズはゼロなので、この手順は不可欠である。

また、DIDEVICEOBJECTDATA 型の配列も宣言する必要がある。この配列は、最高でバッファ サイズと同数の要素を持つことができる。1 度の呼び出しでバッファの内容全体を取得する必要はない。配列内の 1 要素だけを保持して、バッファが空になるまで 1 つずつイベントを取得することができる。

デバイスの取得後は、DirectInputDevice8.GetDeviceData メソッドを使っていつでもバッファ内のイベントを調べたりフラッシュしたりすることができる (「バッファリング データと直接データ」を参照すること)。返された DIDEVICEOBJECTDATA 配列中の各要素は、マウスに対する単一オブジェクトの状態の変化を表す。たとえば、ユーザーがボタン 0 を押してマウスを斜めに移動すると、GetDeviceData に渡された配列 (3 つ以上の要素を持っている場合) は、3 つの要素が埋められる。これらの要素はそれぞれ、ボタン 0 の押下、x 軸の変化、および y 軸の変化を表す。メソッドの戻り値は 3 である。

配列中の要素がどのオブジェクトを指すかは、DIDEVICEOBJECTDATA 型の lOfs メンバを、CONST_DIMOUSEOFS 列挙の定数と比較することで確認できる。これらの各値は、DIMOUSESTATE 構造体または DIMOUSESTATE2 型中のオブジェクトに対するデータのオフセットから導かれる。たとえば、DIMOFS_BUTTON0 が返す値は、DIMOUSESTATE 型中の buttons(0) オフセットと等しい。DIMOFS_BUTTON4 から DIMOFS_BUTTON7 までは、DIMOUSESTATE2 に対してだけサポートされている。

デバイス オブジェクトの状態変化データは、DIDEVICEOBJECTDATA 型の lData メンバに格納される。軸の場合には、座標値がこのメンバ中に返される。ボタン オブジェクトの場合は、lData の下位バイトだけが有意である。上位ビットはボタンが押されたときに設定され、ボタンが離されたときに消去される。言い換えれば、(lData And &H80) がゼロでないとき、ボタンが押されていることになる。

DIDEVICEOBJECTDATA 構造体のほかのメンバの詳細については、「タイム スタンプとシーケンス番号」を参照すること。

次のコードは、バッファ (BufferSize 数の要素を含む) の内容全体を取得し、さまざまなイベントに応答する例である。

' objDIDev は DirectInputDevice オブジェクトである。
Dim diDeviceData(1 To BufferSize) As DIDEVICEOBJECTDATA
Dim NumEvents As Integer
Dim i As Integer

NumEvents = objDIDev.GetDeviceData(diDeviceData, 0)
For i = 1 To NumEvents
    Select Case diDeviceData(i).lOfs
        Case DIMOFS_X
           '  x 軸の移動に反応する。

         Case DIMOFS_Y
           '  y 軸の移動に反応する。

         Case DIMOFS_BUTTON0
           If diDeviceData(i).lData And &H80 Then
             ' Respond to left button pressed.
           Else
             ' Respond to left button released.
           End If

    End Select
Next i


マウス軸データの解釈

マウスの x 軸および y 軸に対して返されるデータは、カーソルではなくマウス自身の動作を示す。測定単位は、マウスのハードウェアが返す値に基づくものであり、ピクセルやその他の画面測定形式とは無関係である。Microsoft® DirectInput® はマウス ドライバと直接通信するので、ユーザーがコントロール パネルで設定するマウスのスピードと加速値は、このデータに影響しない。

マウスから返される軸データは、相対でも絶対でもよい (「相対座標と絶対座標」を参照すること)。マウスは相対的なデバイスなので (ジョイスティックとは異なり、ホームポジションを持たない)、デフォルトでは、相対データが返される。

軸モードは、相対データまたは絶対データのどちらを返すかを指定するものであるが、デバイスを取得する前に変更できるプロパティである (「デバイス プロパティ」を参照すること)。軸モードを "絶対" に設定するには、guid パラメータに DIPROP_AXISMODE 値を指定し、DIPROPLONG 型の lData メンバに DIPROPAXISMODE_ABS を指定して、DirectInputDevice8.SetProperty メソッドを呼び出す。

マウスの軸モードが "相対" の場合、軸座標は、最後の値が返されて以降、軸にそってデバイスが移動した単位数を表す。負の値は、ｘ軸の場合、マウスが左方向に移動したこと、y 軸の場合、ユーザーから離れる方向にマウスが移動したこと、および z 軸 (ホイール) が手前に回転したことをそれぞれ示す。正の値はこれと反対方向の動きを示す。

軸モードが "絶対" の場合、軸座標は、単純に DirectInput が受信した相対動作のすべての累積合計となる。軸座標値は、デバイスの取得時には、特定の値に初期化されていないので、アプリケーションは、絶対値を未知の原点を基準にした相対値として扱う必要がある。デバイスを取得したときは、いつも現在の絶対位置を記録して、それを "仮想原点" として保存することができる。この仮想原点は、その後、デバイスから得られる絶対座標から減算することにより、マウスが取得時点から移動した相対距離を計算することができる。

軸座標に返されるデータは、デバイスの細分性プロパティによっても影響を受ける。マウスの x 軸と y 軸の場合、細分度は通常 1 であり、これは、値の最小変化が 1 であることを意味する。ホイールの場合、細分度が 1 より大きくなることもある。


消失したマウス入力の確認

協調レベルに DISCL_FOREGROUND を設定した状態で、フォーカスがほかのアプリケーションに切り替わる場合 (あるいは使用中のアプリケーションのほかのメニューに切り替わる場合でも)、Microsoft® Windows® がアプリケーションにマウスを強制的に解放させることがある。このため、DirectInputDevice8.GetDeviceData または DirectInputDevice8.GetDeviceStateMouse メソッドからの戻り値 DIERR_INPUTLOST をチェックして、必要に応じてマウスを再取得する必要がある (「デバイスの取得」を参照すること)。

注 : DIERR_NOTACQUIRED エラーを受け取った場合には、マウスの再取得を試みないようにする必要がある。そうしないと、無限ループに入るおそれがある。取得は失敗し、DIERR_NOTACQUIRED エラーを受け取るという繰り返しが永遠に続く。


キーボード データ

Microsoft® DirectInput® を使用するときは、キーボードはテキスト入力デバイスではなく、多数のボタンを備えたゲーム パッドであることを考慮すること。アプリケーションがテキスト入力を必要とするときは、DirectInput のメソッドを使ってはいけない。通常の Microsoft Windows® メッセージからデータを取得するのが最も簡単であり、文字反復、物理キーから仮想キーへの平行移動などの Windows サービスを利用することができるからである。これは、英語以外の言語を使用する場合には特に重要である。英語以外の言語ではキーの特別な解釈が必要となることがあるからである。

データを取得するようにキーボード デバイスを設定するには、パラメータに DIFORMAT_KEYBOARD を指定して、DirectInputDevice8.SetCommonDataFormat メソッドを呼び出す。

以下のトピックでは、キーボード データの取得と解釈について詳細に説明する。

  • キーボードの直接データ
  • キーボードのバッファリング データ
  • キーボード データの解釈
  • 消失したキーボード入力の確認


キーボードの直接データ

キーボードの現在の状態を取得するには、DIKEYBOARDSTATE 型を指定して DirectInputDevice8.GetDeviceStateKeyboard メソッドを呼び出す。

GetDeviceState メソッドは、キーボードの現在の状態のスナップショットを返す。各キーは、DIKEYBOARDSTATE 型を構成する 256 バイトの配列内の 1 バイトによって表される。バイトの上位ビットが設定されていると、キーは、ダウン状態にある。配列は最も便利なように、CONST_DIKEYFLAGS 列挙のメンバによりインデックスが付けられている (「キーボード データの解釈」も参照すること)。

以下のコードは、現在 Esc キーが押下されているかどうかを判定する例である。objDIDev は、DirectInputDevice8 オブジェクトとする。

Dim KeyState As DIKEYBOARDSTATE

Call objDIDev.GetDeviceStateKeyboard(KeyState)
If (KeyState.Key(DIK_ESCAPE) And &H80) Then
    ' キーは押下されている。
End If


キーボードのバッファリング データ

キーボードからバッファリング データを取得するには、バッファ サイズを設定しなければならない (「デバイス プロパティ」を参照すること)。この手順は、バッファのデフォルト サイズがゼロであるので不可欠である。

また、DIDEVICEOBJECTDATA 型の配列も宣言する必要がある。この配列は、最高でバッファ サイズと同数の要素を持つことができる。1 度の呼び出しでバッファの内容全体を取得する必要はない。配列内の 1 要素だけを保持して、バッファが空になるまで 1 つずつイベントを取得することができる。

キーボード デバイスの取得後は、DirectInputDevice8.GetDeviceData メソッドを使っていつでもバッファを調べたりフラッシュしたりすることができる (「バッファリング データと直接データ」を参照すること)。

DIDEVICEOBJECTDATA 配列の各要素は、単一キーの状態変化、すなわち、押下または解放を表す。Microsoft® DirectInput® は、キーボードから直接データを取得するために、コントロール パネルの文字反復の設定はすべて無視する。すなわち、キーストロークは、キーが押下されている時間の長短に関係なく、1 度しかカウントされないということになる。

配列中の要素がどのキーを指すかは、CONST_DIKEYFLAGS 列挙の定数と、DIDEVICEOBJECTDATA 型の lOfs メンバを比較することにより確認できる (「キーボード データの解釈」も参照すること)。

キーの状態変化データは、DIDEVICEOBJECTDATA 型の lData メンバに格納されている。lData の下位バイトだけが有意である。上位ビットはキーが押されたときに設定され、キーが離されたときに消去される。言い換えれば、(lData And &H80) がゼロでないとき、キーが押されていることになる。


キーボード データの解釈

ここでは、DirectInputDevice8.GetDeviceState メソッドおよび DirectInputDevice8.GetDeviceData メソッドが報告するデータのキーの識別について説明する。GetDeviceData からのデータの解釈についての詳細は、「タイム スタンプとシーケンス番号」を参照すること。

重要な点として、Microsoft® DirectInput® アプリケーションは、Microsoft Windows® とは異なる方法でキーボードを読み取る。DirectInput アプリケーションでは、キーボード データは仮想キーを指すのではなく、実際の物理的なキー、つまり、スキャン コードを指す。たとえば、DIK_ENTER はメイン キーボードの Enter キーを指すが、テンキーの Enter キーは指していない。

また、キーボードの違いにより、DirectInput アプリケーションがキーボード データを解釈する方法を変えることができる。たとえば、DirectInput は、拡張キーボード上の各キーに対する定数と共に、国際キーボード上にある追加キーも定義する。NEC キーボードは、PC 拡張キーボードとは異なるスキャン コードをサポートしているので、DirectInput は、可能な限り NEC スキャン コードを PC 拡張スキャン コードに変換する。

これら以外でキーボードに関して考慮すべき事項は、以下のとおりである。

  • また、すべての PC 拡張キーボードに、新しい Windows キー (DIK_LWIN、DIK_RWIN、DIK_APPS) があるわけではない。Windows キーが物理的に使用可能かどうかを決定する方法はない。
  • ラップトップなどの小型コンピュータは、フルセットのキーを実装していない。代わりに、一部のキー (普通はテンキー) をほかのキーと多重化し、補助モードキーによって選択するようにして、個別のスキャン コードをつくらないようにしている。
  • キーボード サブタイプが PC XT または PC AT キーボードを示している場合、DIK_F11、DIK_F12、およびすべての拡張キー (0x7F より大きい DIK_* 値を持つキー) は利用できない。さらに、PC XT キーボードには DIK_SYSRQ がない。
  • 日本語キーボード、特に NEC PC-98 キーボードは、US キーボードとは相当に異なるキー セットを含んでいる。詳細については、「DirectInput と日本語キーボード」を参照すること。


消失したキーボード入力の確認

協調レベルを DISCL_FOREGROUND に設定した状態で、フォーカスがほかのアプリケーションに切り替わる場合、Microsoft® Windows® がアプリケーションにキーボードを強制的に解放させることがあるので、DirectInputDevice8.GetDeviceData メソッドまたは DirectInputDevice8.GetDeviceStateKeyboard メソッドからの DIERR_INPUTLOST 戻り値をチェックして、必要に応じてキーボードを再取得する必要がある (「デバイスの取得」を参照すること)。

注 : DIERR_NOTACQUIRED エラーを受け取った場合には、キーボードの再取得を試みないようにする必要がある。そうしないと、無限ループに入るおそれがある。取得は失敗し、DIERR_NOTACQUIRED エラーを受け取るという繰り返しが永遠に続く。


ジョイスティック データ

データを取得するようにジョイスティック デバイスを設定するには、パラメータに DIFORMAT_JOYSTICK または DIFORMAT_JOYSTICK2 グローバル変数を指定して、DirectInputDevice8.SetCommonDataFormat メソッドを呼び出す (「デバイス データ形式」を参照すること)。

一部のデバイス ドライバは、明示的に要求されるまで Microsoft® DirectInput® に状態の変化を通知しないことがあるので、ジョイスティックのデータを取得する前には必ず DirectInputDevice8.Poll メソッドを呼び出さなくてはならない。詳細については、「ポーリングとイベント通知」を参照すること。

以下のトピックでは、ジョイスティックおよびゲームパッドまたは操縦桿などの入力デバイスからのデータの取得と解釈について説明する。

  • ジョイスティックの直接データ
  • ジョイスティックのバッファリング データ
  • ジョイスティック軸データの解釈
  • 消失したジョイスティック入力の確認


ジョイスティックの直接データ

ジョイスティックの現在の状態を取得するには、DirectInputDevice8.GetDeviceStateJoystick メソッドまたは DirectInputDevice8.GetDeviceStateJoystick2 メソッドを呼び出す。どちらのメソッドを使用するかは、DIFORMAT_JOYSTICK か DIFORMAT_JOYSTICK2 のどちらでデータ形式が設定されたのかによる (「デバイス データ形式」を参照すること)。state パラメータに返されるジョイスティック状態には、軸座標、ボタンの状態、および視点コントローラの状態などがある。

DIJOYSTATE 型または DIJOYSTATE2 型の POV メンバには、4 つまでの視点コントローラの位置が含まれている。これらは、北から時計回り (または前方) の実角度の 100 倍で表される。中心位置は -1 として報告される。5 つの位置しか持たないコントローラの場合、位置は以下のどれか 1 つの値を取る。

  • -1
  • 0
  • 9000
  • 18000
  • 27000

中心位置として、-1 ではなく 65,535 を報告するドライバもある。POV 標識が中心位置にあるかどうかは、次のようにチェックしなければならない。

Dim POVCentered As Boolean
POVCentered = MyDijoystate.POV(0) And &HFFFF

buttons メンバは、バイト配列である。データ型によって、32 個または 128 個の各ボタンに 1 要素が対応する。各ボタンの上位ビットは、ボタンがダウン状態で設定され、アップ状態または存在しない場合に消去される

DIJOYSTATE2 型には、軸の速度、加速度、フォース、およびトルクについての情報を提供する追加メンバがある。

詳細については、「ジョイスティック軸データの解釈」を参照すること。

参照

バッファリング データと直接データ


ジョイスティックのバッファリング データ

ジョイスティックからバッファリング データを取得するには、まず、バッファサイズを設定し (「デバイス プロパティ」を参照すること)、DIDEVICEOBJECTDATA 型の配列を宣言しなければならない。この配列は、最高でバッファ サイズと同数の要素を持つことができる。1 度の呼び出しでバッファの内容全体を取得する必要はない。配列内の 1 要素だけを保持して、バッファが空になるまで 1 つずつイベントを取得することができる。

デバイスの取得後は、DirectInputDevice8.GetDeviceData メソッドを使っていつでもバッファを調べたりフラッシュしたりすることができる (「バッファリング データと直接データ」を参照すること)。

DIDEVICEOBJECTDATA 配列中の各要素は、ジョイスティックに対する単一オブジェクトの状態の変化を表す。たとえば、ユーザーがボタン 0 を押してスティックを斜めに移動すると、GetDeviceData に渡された配列 (3 つ以上の要素を持っている場合) は、3 つの要素が埋められる。これらの要素はそれぞれ、ボタン 0 の押下、x 軸の変化、および y 軸の変化を表す。メソッドの戻り値は 3 である。

配列中の要素がどのオブジェクトを指すかは、DIDEVICEOBJECTDATA 型の lOfs メンバを、CONST_DIJOYSTICKOFS 列挙内の定数と比較することで確認できる。これらのそれぞれの値は、DIJOYSTATE 型中のオブジェクトに対するデータのオフセットと等しい。たとえば、DIJOFS_BUTTON0 が返す値は、DIJOYSTATE 型中の buttons(0) オフセットと等しい。

データ形式が DIFORMAT_JOYSTICK2 で設定された場合は、DIJOYSTATE 内に存在するすべてのデバイス オブジェクトのオフセット定数を使用することができる。ただし、DIJOYSTATE2 の追加メンバに表現されるデバイス オブジェクトには、独自のオフセットを設定する必要がある。この型の内部構造は、Dinput.h ヘッダー ファイルに含まれる同名の C++ 構造体と同じである。

デバイス オブジェクトの状態変化データは、DIDEVICEOBJECTDATA 型の lData メンバに格納される。軸の場合には、座標値がこのメンバ中に返される。ボタン オブジェクトの場合は、lData の下位バイトだけが有意である。上位ビットはボタンが押されたときに設定され、ボタンが離されたときに消去される。

ほかのメンバについては、「タイム スタンプとシーケンス番号」を参照すること。


ジョイスティック軸データの解釈

ジョイスティックの軸値は、マウスの軸値と同様である。スティックを右に動かすと x 軸の戻り値が増し、スティックを手前に引き倒すと y 軸の値が増す。

ジョイスティック軸のデータは、軸の範囲プロパティにより任意の単位に決定される。たとえば、ジョイスティックの x 軸の範囲が 0 から 10,000 までの場合には、単位はジョイスティックの左右の移動の 10,000 分の 1 となり、中心位置は 5,000 となる。軸によっては、細分度プロパティが 1 より大きい場合もあり、その場合には値は丸められる。たとえば、細分度が 10 の場合には、値は 0、10、20 などのように報告される。

軸データは、無効ゾーンという、動作が無視される中心位置の周辺領域によっても影響を受ける。無効ゾーンは、ジョイスティックの少なくとも一方の軸に対する真の中心位置からの小さなずれに対する許容範囲となる。無効ゾーン内の軸の値は、真の中心として報告される。

軸の飽和プロパティとは、範囲の最大値および最小値の許容ゾーンのことである。このゾーン内の軸値は、最小値または最大値として報告される。飽和プロパティの目的は、たとえば、ジョイスティックの頂部の左位置と底部の左位置で報告される最小 x 軸間のわずかな差違を許容することにある。

次の図は、無効ゾーンと飽和ゾーンのエフェクトを示したものである。垂直軸は、軸の戻り値を表す。ここで、min と max は報告された範囲の下限と上限であり、ctr は報告された中心である。水平軸は、ジョイスティックの物理的な位置を示す。ここで、pmin と pmax は、物理的な範囲の限界、pctr は軸の中立点、dmin と dmax は無効ゾーンの限界値、そして smin と smax は上下の飽和ゾーンの境界である。下位飽和ゾーンは pmin と smin の間に存在し、上位飽和ゾーンは smax と pmax の間に存在し、無効ゾーンは dmin と dmax の間に存在する。

ジョイスティック プロパティの詳細については、以下を参照すること。

  • DirectInputDevice8.GetProperty
  • DirectInputDevice8.SetProperty
  • DIPROPRANGE
  • DIACTIONFORMAT

ジョイスティックから返される軸座標は、相対でも絶対でもよい (「相対座標と絶対座標」を参照すること)。ジョイスティックは絶対デバイスなので (マウスとは異なり、軸にそって無限には移動できない)、デフォルトでは絶対データが返される。ジョイスティックの軸モードが "相対" に設定されている場合には、軸座標は、最後の値が返されてから以降の軸にそった移動の単位数を表す。

軸モードは、相対データまたは絶対データのどちらを返すかを指定するものであるが、デバイスを取得する前に変更できるプロパティである (「デバイス プロパティ」を参照すること)。軸モードを "相対" に設定するには、guid パラメータに DIPROP_AXISMODE 値を指定し、DIPROPLONG 型の lData メンバに DIPROPAXISMODE_REL を指定して、DirectInputDevice8.SetProperty メソッドを呼び出す。


CPOINT の使い方

ここでは、C++ でのアプリケーション開発について説明する。


消失したジョイスティック入力の確認

ジョイスティックをフォアグラウンドモードで使用する (「協調レベル」を参照すること) 場合には、フォーカスが他のアプリケーションに切り替わるときに、デバイスを喪失することがある。

DirectInputDevice8.GetDeviceData メソッドまたは DirectInputDevice8.GetDeviceStateKeyboard メソッドからの DIERR_INPUTLOST 戻り値をチェックし、必要に応じてジョイスティックを再取得することができる (「デバイスの取得」を参照すること)。

注 : DIERR_NOTACQUIRED エラーを受け取った場合には、キーボードの再取得を試みないようにする必要がある。そうしないと、無限ループに入るおそれがある。取得は失敗し、DIERR_NOTACQUIRED エラーを受け取るという繰り返しが永遠に続く。

キーボードやマウスとは異なり、Microsoft® Windows® システムはジョイスティックを使用しないので、アプリケーションがバックグラウンドに移行する場合を除き、ジョイスティックへのアクセス権が失われることはない。したがって、どちらのメソッドでも、WM_ACTIVATE メッセージに応えてデバイスを再取得できる。


データ出力

ヒューマン インターフェイス デバイスは、入力の生成と同様に出力を認知することができる。そのようなデバイスにデータ パケットを送信するには、DirectInputDevice8.SendDeviceData メソッドを使用する。

SendDeviceData は、反対に DirectInputDevice8.GetDeviceData として表示することができる。SendDeviceData メソッドと同様、GetDeviceData メソッドは、データの基本単位として DIDEVICEOBJECTDATA 型を使用する。この場合、lOfs メンバに含まれるのは、デバイスのデータ形式のオフセットではなく、データに関連付けられたデバイス オブジェクトのインスタンス ID である。この ID は、デバイス オブジェクトを列挙した後に、DirectInputDeviceObjectInstance.GetType により返される値から抽出できる (オフセット識別子は、選択されたデータ形式での入力を提供するデバイス オブジェクトのためだけに存在するので、出力しか認めないオブジェクトは、オフセットを持つことすらない)。lData メンバには、そのオブジェクトに適したデータが含まれる。lTimeStamp および lSequence メンバは使用しない。これらのメンバは、ゼロに設定しなければならない。

デバイスにデータを送るには、最初に DIDEVICEOBJECTDATA 型の配列を設定し、要求された数の要素をデータで埋めてから、使用するアドレスと要素数を SendDeviceData に渡す。異なるデバイス オブジェクトのデータは、デバイスに送られる単一パケットに結合される。

データ パケットの形式は、パケット内の使用されないフィールドの処理方法と同じで、デバイスによって異なる。デバイスによっては、フィールドをオプションとして扱う。つまり、データが提供されない場合、オブジェクトの状態は前と同じである。一般的には、特にデータがフィールドに提供されない場合であっても、すべてのフィールドは重要である。たとえば、単一のキーボード LED にデータを送ると、ほかの 2 つの LED のデータはゼロで、それらの LED はオフであると仮定される。ただし、DISDD_CONTINUE フラグを使用してこの動作を無効にすることができる。この場合は、ほかの 2 つの LED のデータは、最後に送信した値となる。

デバイス オブジェクトの型の識別子は、HID 使用ページと使用コードを DirectInputDevice8.GetObjectInfo に渡した後で取得できる。

次の例では、コードが繰り返し実行される場合、キーボード上の LED は繰り返し点滅する。LED の状態は、データ バイトの上位ビットにより決定されるものとする。デバイス オブジェクト インスタンスの識別子 NumLockID、CapsLockID、および ScrollLockID は以前に取得され、diDevKeyboard は以前に定義された DirectInputDevice8 オブジェクトである。

Private Sub FlashLEDs()
    Const ARRAYSIZE = 4
    Static rgiBits(ARRAYSIZE-1) As Integer
       rgiBits(0) = 1
       rgiBits(1) = 2
       rgiBits(2) = 4
       rgiBits(3) = 2
    Static iLooper As Integer
       iLooper = 0
    Dim cdod As Long
       cdod = 3                  ' 項目数。
    Dim rgdod(3) As DIDEVICEOBJECTDATA
    Dim i as Integer

    ' lTimeStamp および lSequence は 0 に設定すること。
    For i = 0 To 3
        rgdod(i).lTimeStamp = 0
        rgdod(i).lSequence = 0
    Next i

    rgdod(0).lOfs = NumLockID
    rgdod(1).lOfs = CapsLockID
    rgdod(2).lOfs = ScrollLockID

    Select Case (rgiBits(iLooper) And 1)
        Case Is = 0
            rgdod(0).lData = 0
        Case Is = 1
            rgdod(0).lData = &H80          ' NumLock ライトのオン/オフ
    End Select

    Select Case (rgiBits(iLooper) And 2)
        Case Is = 0
            rgdod(1).lData = 0
        Case Is = 1
            rgdod(1).lData = &H80          ' CapsLock ライトのオン/オフ
    End Select

    Select Case (rgiBits(iLooper) And 4)
        Case Is = 0
            rgdod(2).lData = 0
        Case Is = 1
            rgdod(2).lData = &H80          ' ScrollLock ライトのオン/オフ
    End Select

    iLooper = (iLooper + 1) Mod ARRAYSIZE  ' 0 から 3 までループする。

    Call diDevKeyboard.SendDeviceData(cdod, rgdod, 0)

End Sub


アクション マッピング

従来、アプリケーションは特定のボタンや軸に対して独自のイベント マッピングを行っていた。たとえばカーレーシング ゲームの場合、ユーザーのジョイスティックやマウスの x 軸が車の運転用コントロールに最適であると想定される。新規デバイスや特殊デバイスを組み込む唯一の方法は、ユーザーが運転用に使用する回転軸などその他の軸を指定できるように、構成オプションを提供することであった。さらに、アプリケーションは、インストールされたどのデバイスがゲームに最適であるかを知る手段はなかったので、ユーザーは通常、メニューからデバイスを選択したり、適切なデバイスだけが接続されていることを確認したりしなければならなかった。

アクション マッピングを使うと、デバイスとデバイス オブジェクトの最適な使用法に関してさまざまなことを想定する必要はなくなる。その代わりに、アプリケーションが、可能な限りアクションと仮想コントロールをバインドする。アプリケーションは、x 軸からデータを取得して車を左右に動かすのではなく、DIAXIS_DRIVINGR_STEER という仮想コントロールからデータを取得することになる。Microsoft® DirectInput® は、仮想コントロールを物理コントロール、つまりデバイス オブジェクトに割り当てる。割り当ての際には、アプリケーションのジャンル、ユーザー設定、デバイス メーカーからの情報、およびユーザーのデバイス構成が考慮される。

また、アクション マッピングを使うと、すべてのデバイスのデータが、特定のデバイスに依存しない形式で返されることにより、入力ループが簡素化される。単一のアクションを複数のデバイスにマップでき、そのアクションに対し、どのデバイスを読み取り中かにかかわらず、入力ループが同一の方法で応答することができる。

以下のトピックでは、アクション マッピングの実装に必要な手順の詳細を説明する。

  • アクション マップの準備
  • 一致するデバイスの検索
  • アクション マップの構成
  • デバイスのユーザー構成
  • アクション データの取得
  • 開発中のファイルの管理


アクション マップの準備

アクション マップとは、アプリケーションのアクションと、仮想コントロールやデバイス オブジェクトへのマッピングに関する情報を格納している DIACTIONFORMAT 型である。この型がアプリケーションと Microsoft® DirectInput® の間でやりとりされ、最終的なマッピングが確立される。ここでは、マップの初期化方法について説明する。

1. アプリケーション アクションの定義

DirectInput アクション マッピングを実装する際の第 1 ステップは、アプリケーション内のどの入力ドリブン アクションをデバイス オブジェクトにマップする必要があるかを決定することである。軸やボタンによって実行できるアクションの場合、軸とボタンの両方の入力タイプに独立したアクションを定義しなければならない。デバイスが適切な軸を持たない場合に備えて、重要な機能にはすべてボタン アクションを定義することが推奨される。

次のアクション値の列挙例は、カーレーシング ゲームにより定義されるものとする。軸アクションは "eA" で始まり、ボタン アクションは "eB" で始まる。

Enum eGameActions
    eA_STEER        'ハンドル
    eB_STEER_LEFT   'ハンドルを左に切る
    eB_STEER_RIGHT  'ハンドルを右に切る
    eA_ACCELERATE   '速度変更
    eB_ACCELERATE   '加速
    eB_DECELERATE   '減速
    eA_BRAKE        'ブレーキ
    eB_BRAKE        'ブレーキ
    eB_UPSHIFT      '高速ギアにシフト
    eB_DOWNSHIFT    '低速ギアにシフト
    eB_CYCLEVIEW    '次のビューに転換
    eB_COURSEVIEW   'コース ビューの切り替え
    eB_DRIVERVIEW   '運転席ビュー
    eB_BRAKEBIAS    'ブレーキ バイアス
    eA_VOLUME       '音量
    eB_MUTE         'サウンドの切り替え
End Enum

Const NUM_MY_ACTIONS = 16

この例では、アクションは列挙値として定義されている。ただし、ほかの 32 ビット データ型をとることもできる。デバイス データを取得する場合、定義したアクション値はすべて取得されるので、その値を自由に処理できる。

2. ジャンルの定義

第 2 ステップは、アプリケーションの属するジャンルを決定することである。ジャンルにより、仮想コントロールのセットが定義される。適切なジャンルを選択することで、アプリケーション アクションに対して最適な仮想コントロールを取得できる。メーカーがデバイスにデフォルト マッピングを設定する場合、メーカーは DirectInput で定義されたジャンルのうち 1 つ以上をサポートしなければならない。ジャンル一覧については、「アクション マッピング定数」を参照すること。

この例のゲームの場合は、当然 DIVIRTUAL_DRIVING_RACE ジャンルを選択する。このジャンルには以下の仮想コントロールが含まれている。

優先順位 1 のコントロール

DIAXIS_DRIVINGR_STEER
DIAXIS_DRIVINGR_ACCELERATE
DIAXIS_DRIVINGR_BRAKE
DIBUTTON_DRIVINGR_SHIFTUP
DIBUTTON_DRIVINGR_SHIFTDOWN
DIBUTTON_DRIVINGR_VIEW
DIBUTTON_DRIVINGR_MENU

優先順位 2 のコントロール

DIAXIS_DRIVINGR_ACCEL_AND_BRAKE
DIHATSWITCH_DRIVINGR_GLANCE
DIBUTTON_DRIVINGR_ACCELERATE_LINK
DIBUTTON_DRIVINGR_AIDS
DIBUTTON_DRIVINGR_BOOST
DIBUTTON_DRIVINGR_BRAKE
DIBUTTON_DRIVINGR_DASHBOARD
DIBUTTON_DRIVINGR_DEVICE
DIBUTTON_DRIVINGR_GLANCE_LEFT_LINK
DIBUTTON_DRIVINGR_GLANCE_RIGHT_LINK
DIBUTTON_DRIVINGR_MAP
DIBUTTON_DRIVINGR_PAUSE
DIBUTTON_DRIVINGR_PIT
DIBUTTON_DRIVINGR_STEER_LEFT_LINK
DIBUTTON_DRIVINGR_STEER_RIGHT_LINK

優先順位 1 のコントロールと 優先順位 2 コントロールの間に機能上の差異はない。優先順位 1 のコントロールは、デバイス メーカーがデフォルト マッピングとしてサポートすることが望ましいコントロールである。ただし、どの仮想コントロールも、デバイスによりサポートされる保証はない。

3. コントロールやデバイス オブジェクトへのアクションの割り当て

アクション マップ作成の次のステップでは、それぞれのアプリケーション アクションに、該当ジャンルで定義された 1 つ以上の仮想コントロールを関連付ける。この処理を行うには、DIACTION 型の配列を宣言して初期化する。配列内の構造体はそれぞれ、アクション値、それに関連付けられた仮想コントロール、およびそのアクションを説明する登録名を指定する。その他のメンバはゼロとして残す。これらのメンバの値は後で DirectInput により指定される。

DIACTION 配列の要素を使って、アクションをキーボードの特定のキー、またはマウスの特定のボタン、あるいは Microsoft DirectPlay® 音声デバイスにマップすることもできる。そうすることで、仮想コントロールからの入力に限らずすべての入力で、簡略化された入力ループを利用できる。たとえば、アプリケーション定義アクション eB_UPSHIFT を DIBUTTON_DRIVINGR_SHIFTUP 仮想コントロールと、Page Up キーの両方にマップするとしよう。データを取得する場合、入力源がジョイスティック ボタンとキーボードのどちらであるかにかかわらず、eB_UPSHIFT を取得する。

以下の例は、カーレーシング ゲーム用のアクション マップの宣言を開始している。

Dim rgActions(20) As DIACTION

' ジャンル定義の仮想軸。
With rgActions(0)
  .lAppData = eA_STEER
  .lSemantic = DIAXIS_DRIVINGR_STEER
  .lFlags = 0
  .ActionName = "Steer"
End With
With rgActions(1)
  .lAppData = eA_ACCELERATE
  .lSemantic = DIAXIS_DRIVINGR_ACCELERATE
  .lFlags = 0
  .ActionName = "Accelerate"
End With
With rgActions(2)
  .lAppData = eA_BRAKE
  .lSemantic = DIAXIS_DRIVINGR_BRAKE
  .lFlags = 0
  .ActionName = "Brake"
End With
' その他の宣言。

ただし、次の例のように、Sub プロシージャを使って DIACTIONFORMAT 型の DIACTION 配列に値を直接割り当てた方が効率的な場合がある。

Dim m_diaf As DIACTIONFORMAT
Dim m_NumberofSemantics As Long

Private Sub Form_Load()

m_NumberofSemantics = 0

AddAction eA_STEER, DIAXIS_DRIVINGR_STEER, 0, "Steer"
AddAction eA_ACCELERATE, DIAXIS_DRIVINGR_ACCELERATE, 0, "Accelerate"
AddAction eA_BRAKE, DIAXIS_DRIVINGR_BRAKE, 0, "Brake"

' ジャンル定義の仮想ボタン。

AddAction eB_UPSHIFT, DIBUTTON_DRIVINGR_SHIFTUP, 0, "Upshift"
AddAction eB_DOWNSHIFT, DIBUTTON_DRIVINGR_SHIFTDOWN, 0, "DownShift"
AddAction eB_CYCLEVIEW, DIBUTTON_DRIVINGR_VIEW, 0, "Change View"

' 任意のボタンや軸に割り当て可能な
' ジャンル未定義のアクション。

AddAction eA_VOLUME, DIAXIS_ANY_1, 0, "Volume"
AddAction eB_MUTE, DIBUTTON_ANY, 0, "Toggle Sound"

' 特定のキーに割り当てる必要がある
' ジャンル未定義のアクション。

AddAction eB_DRIVERVIEW, DIKEYBOARD_1, 0, "Driver View"
AddAction eB_COURSEVIEW, DIKEYBOARD_C, 0, "Course View"
AddAction eB_BRAKEBIAS, DIKEYBOARD_B, 0, "Brake Bias"

' キーと仮想コントロールにマップされたアクション。

AddAction eB_UPSHIFT, DIKEYBOARD_PRIOR, 0, "Upshift"
AddAction eB_DOWNSHIFT, DIKEYBOARD_NEXT, 0, "Downshift"
AddAction eB_STEER_LEFT, DIKEYBOARD_LEFT, 0, "Steer Left"
AddAction eB_STEER_RIGHT, DIKEYBOARD_RIGHT, 0, "Steer Right"
AddAction eB_ACCELERATE, DIKEYBOARD_UP, 0, "Accelerate"
AddAction eB_DECELERATE, DIKEYBOARD_DOWN, 0, "Decelerate"
AddAction eB_BRAKE, DIKEYBOARD_END, 0, "Brake"

' ボタンと仮想コントロールおよびキーにマップされたアクション。

AddAction eB_UPSHIFT, DIMOUSE_BUTTON0, 0, "Upshift"
AddAction eB_DOWNSHIFT, DIMOUSE_BUTTON1, 0, "Downshift"

End Sub

Private Sub AddAction(user As Long, semantic As Long,_
                             flags As Long, strName As String)
ReDim Preserve m_diaf.ActionArray(m_NumberofSemantics)

With m_diaf.ActionArray(m_NumberofSemantics)
    .lAppData = user
    .lSemantic = semantic
    .lFlags = flags
    .ActionName = strName
End With
m_NumberofSemantics = m_NumberofSemantics + 1

End Sub

この例で、一部のアクションは、キーボード マッピング定数を使って実際のキーにマップされている。同様に、マウスのボタンと軸へのマッピングも、マウス マッピング定数を使って行うことができる。

DIACTION 配列は、ジャンル、アプリケーション、および軸データの適切なスケーリングに関する情報を格納する DIACTIONFORMAT 型の一部である。アクション マッピング プロセスの全体にわたり、この型の同じインスタンスを使用する。一部のメンバはすぐには使用されないが、次のステップ「一致するデバイスの検索」に移る前に、型全体に値を設定できる。


一致するデバイスの検索

アプリケーション アクションと、それらのアクションのマップ先である仮想コントロールやデバイス オブジェクトの定義が済んだら、次のステップでは、システム上のデバイスを列挙して、目的の仮想コントロールに最適なデバイスを検索する。

これを行うには、DIACTIONFORMAT 型を DirectInput8.GetDevicesBySemantics に渡す。このメソッドは、DirectInput8.GetDIDevices とよく似た動作をする。

特定のコントロールに一致するようにユーザーが構成したデバイスは、常に最初に列挙される。たとえば、ユーザーがホイールをドライビング ゲームのプライマリ ステアリング デバイスとして構成している場合は、DIAXIS_DRIVINGR_STEER をサポートするデバイスが要求されるとホイールが最初に列挙される。DIAXIS_DRIVINGR_STEER をサポートするジョイスティックなどのほかのデバイスがあっても、ユーザーによって構成されていなければ、ホイールが優先される。それ以外の場合、利用可能なデバイスの列挙順は、要求されたコントロールに一致する度合いにより決まる。

列挙を取得すると、各デバイスのデフォルト アクション マッピングの取得、不要なマッピングの変更、ユーザーがデバイスを再構成する機能の設定、およびアクション マップの適用を行うことができる。これらのステップについては、「アクション マップの構成」で説明する。


アクション マップの構成

各デバイスが列挙されたら、デフォルト アクション マップの取得、デフォルト マップへの変更、および最終マッピングの適用を行うことができる。

1. デバイスの取得

列挙が完了したら、DirectInputEnumDevices8.GetItem メソッドを使って DirectInputDeviceInstance8 クラスのインスタンスを取得できる。DirectInputDeviceInstance8.GetGuidInstance でデバイス GUID を取得し、取得したデバイス GUID を DirectInput8.CreateDevice に渡すことができる。結果として得られる DirectInputDevice8 オブジェクトは、アプリケーションで使用するためにグローバル変数として保存できる。また、アクション マップを構成する前に、このオブジェクトのメソッドを使って、検証または変更したいデバイスのプロパティを取得または設定できる。

2. デフォルト アクション マップの取得

デバイスのデフォルト アクション マップを取得するには、DirectInputDevice8.BuildActionMap を呼び出す。Microsoft® DirectInput® は、DIACTIONFORMAT 型に指定された仮想コントロールのリストを取り出し、これらのコントロールを物理デバイス オブジェクトにマップしようとする。結果は同じ型に返される。それぞれの DIACTION 要素の dwHow メンバを確認して、コントロールが正常にマップされたかどうかを調べる必要がある。正常ならば、ユーザーによる構成やデバイス メーカーによる構成など、オブジェクトの選択にどのような基準が使用されたかを突き止めることもできる。

3. アクション マップへの変更

この時点で、デフォルト マッピングを変更できる。ただし、変更は推奨されない。DIACTION 型の lSemantic メンバを検証し、どのデバイス オブジェクトがアクションにマップされたかを確認したら、マップの値を変更できる。たとえば、DIJOFS_BUTTON9 にマップされているアクションを、トリガ ボタンにマップし直したい場合、アクション マップを適用する前に、この値を DIJOFS_BUTTON0 に変更する。

4. アクション マップの適用

DIACTIONFORMAT 型に含まれるデバイスのマッピングが適切であることを確認したら、DirectInputDevice8.SetActionMap を呼び出す。それぞれの DIACTION 型の uAppData メンバに割り当てた値は、この時点で、dwSemantic メンバに指定されたコントロールにバインドされる。これは次に特定のデバイス オブジェクトにバインドされる。

5. 複数デバイスのマッピング

ステップ 1 から 4 までを、アプリケーションで使用するそれぞれのデバイスに対して実行する。アクションをジョイスティックとキーボードの両方にマップするとしよう。レーシング ゲームの例で、ゲームに eB_DRIVERVIEW として定義されたアクションは、DIACTION 配列でキーボードのキーにマップされた。

その例では、キーボード以外のデバイスに対して BuildActionMap が呼び出されると、その要素の DIACTION 型の lHow メンバが DIAH_UNMAPPED に設定される。各デバイスが順に列挙されるのに従い、DIAH_UNMAPPED 以外の値が返されるまで、lHow メンバの検証を続ける。これは、現在マップされている対象のデバイスがキーボードであり、アクションが要求されたキーに正常にマップされたことを示す。

正常にマップされたアクションも、別のデバイスにマップできる。この例では、eB_UPSHIFT が 2 つの DIACTION 型に設定される。

デバイスが列挙されるのにしたがい、eB_UPSHIFT アクションは 1 つ以上のジョイスティックやその他のゲーム コントローラの適切なボタンにマップされ、次にキーボードのキーに再びマップされる。

6. 構成の表示

ユーザーにデバイスへのアクションのマップ状況を示すには、DICD_DEFAULT フラグを DirectInput8.ConfigureDevices に渡す。次の図に示すように、デバイスのマッピング図を含むプロパティ シートが、表示専用モードで表示される。イメージを表示するメカニズムの詳細については、「アクション マッピングの使い方」のチュートリアルを参照すること。

デバイス メーカーからデバイス イメージが提供されていない場合、マッピングは次の図のようにテキスト モードで表示される。

注 : Microsoft® Windows® キーは、アプリケーションの協調レベルで排他協調レベルを通して受動的に、または DISCL_NOWINKEY フラグを使って能動的に無効にする場合でも、デフォルトのアクション マッピング UI が表示されている間はアクティブになる。

プロパティ シートについての詳細情報は、「デバイスのユーザー構成」を参照すること。


デバイスのユーザー構成

Microsoft® DirectInput® には、アプリケーションからプロパティ シートを呼び出す機能がある。これにより、ユーザーはデバイスをそのアプリケーション用に構成し、現在の構成を見ることができる。デバイス メーカーの対応によっては、このプロパティ シートをさまざまなビューで表示できる。

ユーザー構成を有効にするには、目的のマッピングを記述した DIACTIONFORMAT 型を含む DICONFIGUREDEVICESPARAMS 型を、DICD_EDIT フラグと共に DirectInput8.ConfigureDevices メソッドに渡す。通常、この処理は、アプリケーションで使用されるすべてのデバイスに対して DirectInputDevice8.BuildActionMap を呼び出した後で行う。

次の図は、編集モードの典型的なプロパティ シートを示している。

デバイス メーカーからデバイス イメージが提供されていない場合、マッピングは次の図のようにテキスト モードで表示される。

注 : Microsoft® Windows® キーは、アプリケーションの協調レベルで排他協調レベルを通して受動的に、または DISCL_NOWINKEY フラグを使って能動的に無効にする場合でも、デフォルトのアクション マッピング UI が表示されている間はアクティブになる。

デバイスのプロパティ ページには、各 DIACTION 型の ActionName メンバに指定された登録名のリストが表示される。デバイスに対して既に BuildActionMap を呼び出している場合、プロパティ ページでは、デバイスのイメージ上に、アクションがマップされたデバイス オブジェクトを指す線と、コールアウトとしてこれらの名前も表示される。

これにより、ユーザーはまずコントロールを選択し、次にメニューからアクションを選択して、ゲームのアクションを割り当て直すことができる。ユーザーがプロパティ シートを閉じると、メソッドが返り、渡した DIACTIONFORMAT 型に変更内容が格納される。その後、同じ型を DirectInputDevice8.SetActionMap に渡すと、新しいマッピング設定を実装することができる。


アクション データの取得

アクションをマップしたデバイスからバッファ データを取得するには、マップされていないデバイスの場合と同様に、DirectInputDevice8.GetDeviceData を呼び出す。ただし、DIDEVICEOBJECTDATA 型の lOfs メンバを検証することでデバイス オブジェクトを識別するのではなく、lUserData メンバからオブジェクトに関連付けられたアクションを取得する。これは、DIACTION 型内のデバイスに渡したのと同じ値である。

アクションは複数のデバイスへの関連付けが可能であることに注意すること。両方のデバイスから別個にデータを取得する必要があるが、データをどこから取得するかにかかわらず、同じルーチンを使ってデータを処理できる。

次のサンプル コードは、ドライビング シミュレーションのゲーム ループの一部とする。ここでは、m_Devices 配列内のすべてのデバイスからデータを取得する。この配列には m_nDevices 要素が格納されている。

Dim iDevice As Integer
For iDevice = 1 To m_nDevices
    Dim didod(BUFFERSIZE) As DIDEVICEOBJECTDATA

    ' データの有無をデバイスにポーリングする。
    m_Devices(iDevice).Poll

    ' 利用可能なデータの個数を判定する。
    m_nItems = m_Devices(iDevice).GetDeviceData(didod, 0)

    ' アクションを処理する。どのデバイスから返されたかは問わない。
    For i = 0 To m_nItems
        Select Case didod(i).lUserData
            Case eA_STEER:
                Call SteerCar (didod(i).lData)
            Case eB_UPSHIFT:
                If (didod(i).lData & &H80) Then
                    Call ShiftGears (UPSHIFT)
            .
            .
            .
        End Select
    Next
Next

注 : DIAXIS_DRIVINGR_STEER または DIAXIS_SPACESIM_LATERAL などの特定のジャンルの軸定数は、絶対的なジョイスティック データに対して使用される。アクション マッパーは、この仮想コントロールを絶対データを返すデバイス オブジェクトにマップする。アプリケーションでは、このデバイスから返されたデータを適切に処理する必要がある。ただし、DIMOUSE_XAXIS などのデバイス定数は、相対データを返すことが想定されている。

データを取得するときは、1 つのデバイス オブジェクが別のデバイス オブジェクトのデータを上書きしないように、各データ ソースを個別に処理する必要がある。たとえば、方向を制御する次の DIACTION 型はアクション マップで使用される。

With rgActions(0)
  .lAppData = INPUT_LEFTRIGHT_ABS_AXIS
  .lSemantic = DIAXIS_SPACESIM_LATERAL
  .lFlags = 0
  .ActionName = "Turn"
End With
With rgActions(1)
  .lAppData = INPUT_LEFTRIGHT_REL_AXIS
  .lSemantic = DIMOUSE_XAXIS
  .lFlags = 0
  .ActionName = "Turn"
End With
With rgActions(2)
  .lAppData = INPUT_TURNLEFT
  .lSemantic = DIKEYBOARD_LEFT
  .lFlags = 0
  .ActionName = "Turn left"
End With
With rgActions(3)
  .lAppData = INPUT_TURNRIGHT
  .lSemantic = DIKEYBOARD_RIGHT
  .lFlags = 0
  .ActionName = "Turn right"
End With

アプリケーションの入力ループでは、次の case ステートメントでこれらのアクションのデータを処理する。

Select Case adod(j).lUserData
    Case INPUT_LEFTRIGHT_ABS_AXIS:
        g_dwAbsLR = adod(j).lData
    Case INPUT_LEFTRIGHT_REL_AXIS:
        g_dwRelLR = adod(j).lData
    Case INPUT_TURNLEFT:
        g_bLeft = (adod(j).lData <> 0)
    case INPUT_TURNRIGHT:
        g_bRight = (adod(j).lData <> 0)
End Select

データ ソースの割り当てに関して、すべてのデータ ソースが 1 つの汎用の "turn" 変数に割り当てられるのではなく、各データ ソースが個別の変数に割り当てられることに注意すること。データ ソースが汎用の変数を共有する場合、左矢印 (←) キーを押したままジョイスティックを移動すると、キーボード情報が失われる。これは、ジョイスティック データが汎用の変数を上書きするからである。

変数に対してと同様に、データに対してもさまざまな処理方法がある。どのような処理方法を使用する場合でも、予期しない情報の損失を避けるためにデータの処理には注意する必要がある。


開発中のファイルの管理

開発サイクルにおいては、頻繁なアクション マップの変更、Microsoft® DirectX® の再インストール、複数ユーザー、およびその他通常の開発状況によって、使用しない .ini ファイルや日付の古い .ini ファイルが累積する場合がある。このようなファイルが原因で、予期しないマッピングや "最新" レポート (DIEDBS_RECENTDEVICE) が、この値が返されることを予期していないデバイスに対して返される可能性がある。そのため、使用しない .ini ファイルをときどき削除することが望ましい。これらのファイルは、C:\Program Files\Common Files\DirectX\DirectInput\User Maps にある。

注 : ここに示した推奨手順は、開発サイクルにおいて、開発環境を最新の状態にするために手動で実行すべき手順である。ユーザーの優先設定を失う可能性があるため、出荷アプリケーションでは決してユーザー マップを削除してはならない。


フォース フィードバック

フォース フィードバックとは、入出力デバイス (たとえば、ジョイスティックに組み込まれているモーター) にプッシュあるいは抵抗を生成することである。Microsoft® DirectInput® では、互換性のあるドライバを持つデバイスにフォース フィードバック エフェクトを生成することができる。

以下のトピックでは、フォース フィードバックの概念を紹介する。

  • フォース フィードバックの基本概念
  • エフェクトの列挙
  • ファイルからのエフェクトの読み込み
  • サポートされるエフェクトについての情報
  • エフェクトの作成
  • エフェクトの方向
  • エンベロープとオフセット
  • エフェクトの再生
  • エフェクトのダウンロードとアンロード
  • エフェクトの変更
  • ゲイン
  • フォース フィードバック状態
  • エフェクト オブジェクトの列挙
  • エフェクトのタイプ


フォース フィードバックの基本概念

フォース フィードバックのうち特殊なインスタンスを "エフェクト" と言い、プッシュや抵抗を "フォース" と言う。多くのエフェクトは、以下のカテゴリのいずれかに属する。

  • コンスタント フォース － 単一方向の一定のフォース
  • 傾斜フォース － 一定の率で大きさが増加または減少するフォース
  • 周期的エフェクト － 定義された波形パターンで変化するフォース。
  • 条件 － 軸に沿った動きまたは動作への反応。たとえば、ジョイスティックの動作に対して抵抗を生み出す摩擦エフェクトや、ジョイスティックがある位置から動かされた後で、スティックをその位置に戻そうとするスプリング エフェクトである。

フォースの強さを "マグニチュード" という。マグニチュードは、0 (フォースなし) から 10,000 (デバイスの最大フォースで、C/C++ および Visual Basic の場合、DI_FFNOMINALMAX として定義されている) の範囲の単位で測定される。負の値は、反対の方向にあるフォースを示す。マグニチュードは比例的な単位である。たとえば、フォース 10,000 はフォース 5,000 の 2 倍の大きさである。

傾斜フォースには、初期マグニチュードと終期マグニチュードがある。周期的エフェクトでは、基本的マグニチュードは波の頂点でのフォースとなる。

フォースの "方向" はフォースが来る方向である。ある軸上の正のフォースは正から負のほうへ押す力である。

また、エフェクトには "継続時間" がある。これは、マイクロ秒単位で測定される。周期的エフェクトには、"周期" または 1 サイクルの継続時間があり、これらもマイクロ秒単位で測定される。周期的エフェクトの "フェーズ" とは、再生開始箇所の波にそって存在するポイントのことである。

次の図は、マグニチュード 5,000、つまりデバイスの最大フォースの半分での鋸歯周期的エフェクトを表す。水平軸はエフェクトの継続時間を、垂直軸はマグニチュードをそれぞれ表す。中央線よりも上のポイントは、エフェクトに定義された方向における正のフォースを、下のポイントは負のフォース、すなわち反対方向のフォースを表す。

さらにフォースは、"エンベロープ" によって形成される。エンベロープは、"アタック値" と "フェード値" を定義する。アタック値とフェード値により、始点と終点間のエフェクトのマグニチュードが変化する。アタックとフェードには継続時間がある。継続時間は、マグニチュードが "保持値" に到達するのに必要な時間、または保持値から外れるのに要する時間を決定する。保持値とは、エフェクトの中間部のマグニチュードのことである。

次の図は、エンベロープを示している。アタック レベルは 8,000、フェード レベルは 1,000 に設定されている。保持レベルは、このエンベロープを適用したフォースの基本的マグニチュードによって定義される。この例では保持レベルは 5,000 である。このケースでは、アタックの方が保持よりも大きいことに注意すること。これは、エフェクトの初期に強いキックを与えることになる。アタック レベルとフェード レベルの両方が保持レベルより大きいことも小さいこともある。

次の図は、最初の図の周期的エフェクトにエンベロープを適用した結果を示す。マグニチュードの負側では、エンベロープが鏡写しになっている。アタック値 8,000 が意味するのは、一方の方向のフォースの初期マグニチュードが、最大フォースの 80% になるということである。

周期的エフェクトと条件は、すべて、"オフセット" の追加によっても変更することができる。オフセットとは、波形を基本レベルよりも上または下にシフトする量を定義するものである。鋸歯の例に正のオフセットを適用した実際のエフェクトでは、正のフォースを強め、負のフォースを弱めることになる。すなわち、フォースの波形では、一方向への波の頂点が、他方向への波の頂点よりも高くなる。

また、エフェクトの全体的マグニチュードは、"ゲイン" によって増減可能である。ゲインとは、オーディオにおける音量コントロールに類似している。単一のゲイン値を 1 つのデバイスのすべてのエフェクトに適用できるので、これを使って、いろいろなハードウェアに対してフォースを強めたり、弱めたりする補正を加えることができる。また、ユーザーの好みに対応することもできる。


エフェクトの列挙

DirectInputDevice8.GetEffectsEnum メソッドは、デバイスによりサポートされるエフェクトを列挙する。このメソッドは、サポートされるエフェクトのコレクションを表す DirectInputEnumEffects オブジェクトを返す。DirectInputEnumEffects の各メソッドを使うと、特定のエフェクトに関する情報を取得できる。

"サポートされるエフェクト" と "生成されるエフェクト" ("エフェクト オブジェクト") の両者を区別することが重要である。サポートされるエフェクトは、エンベロープによって形成できるコンスタント フォースである。しかし、このエフェクトには、マグニチュード、方向、継続時間、アタックまたはフェードなどのプロパティがまったくない。アプリケーションでエフェクト オブジェクトを生成するときは、これらのプロパティを設定する。サポートされるエフェクトは、それぞれ異なるパラメータを持つ多くのエフェクト オブジェクトによって表すことができる。たとえば、それぞれ異なる継続時間、マグニチュードおよび方向を持つ複数のコンスタント フォースによって表すことができる。

次のコードは、アプリケーションがハードウェア固有のエフェクトを列挙して、Microsoft® SideWinder® ジョイスティックによりサポートされる固有のエフェクトを探す例である。目的のエフェクトが見つからない場合は、アプリケーションは標準エフェクトのいずれかを代用する。

Const BasketballDribble = _
        "{E84CD1AC-81FA-11D0-94AB-0080C74C7E95}"
Dim diEnumEffects As DirectInputEnumEffects
Dim EffGuid As String
Dim i As Integer

' diDev は DirectInputDevice オブジェクトである。
Set diEnumEffects = didev.GetEffectsEnum(DIEFT_HARDWARE)
For i = 1 To diEnumEffects.GetCount
  If diEnumEffects.GetEffectGuid(i) = BasketballDribble Then
    EffGuid = BasketballDribble
    Exit For
  End If
Next i
If EffGuid <> BasketballDribble Then
  EffGuid = "GUID_Sine"
  ' ここで、列挙されたドリブルのパラメータを設定する。
  .
  .
  .
End If

最後に EffGuid を DirectInputDevice8.CreateEffect に渡す。


ファイルからのエフェクトの読み込み

Microsoft® DirectX® SDK で提供される Force Editor、または同じファイル フォーマットを使用する別のアプリケーションを使って、エフェクトをデザインし、ファイルに保存することができる。実行時にこれらのエフェクトを読み込むことで、任意のアプリケーションで使用することができる。

エフェクトを読み込むには、DirectInputDevice8.CreateEffectFromFile メソッドを呼び出す。その後、生成される DirectInputEffect オブジェクトを通常どおり使用できる。


サポートされるエフェクトについての情報

Microsoft® DirectX® for Microsoft Visual Basic® では、サポートされるエフェクトに関する情報は、DirectInputEnumEffects 列挙オブジェクトから取得しなければならない。「エフェクトの列挙」を参照すること。

次のサンプル コードは、最初に列挙されたエフェクトに関する情報を取得して、そのエフェクトを停止または再起動せずにエフェクトの方向を変更できるかどうかを調べる。diEnumEffects は初期化された DirectInputEnumEffects オブジェクトとする。

Dim params As Long
params = diEnumEffects.GetDynamicParams(1)
If params And DIEP_DIRECTION Then
  Debug.Print "Direction is dynamic."
End If


エフェクトの作成

エフェクト オブジェクトを生成するには、DirectInputDevice8.CreateEffect メソッドを使用する。次のサンプル コードでは、didev はDirectInputDevice8 オブジェクトを指している。この例では、半秒間に全力でジョイスティックをユーザーから離れる方向へ引くという、非常に単純なエフェクトが生成される。

Dim effectInfo As DIEFFECT
Dim objDIEffect As DirectInputEffect

With effectInfo
  .constantForce.lMagnitude = 10000
  .lGain = 10000
  .lDuration = 500000
  .x = 18000
  .lTriggerButton = -1  ' トリガ ボタンなし
End With

didev.Acquire
Set objDIEffect = didev.CreateEffect("GUID_ConstantForce", effectInfo)

最初のパラメータには、事前定義された GUID の 1 つ、または、ハードウェア ドキュメントや DirectInputEnumEffects.GetEffectGuid メソッドで列挙されたエフェクトとして取得された、文字列形式の実際の GUID を使用できる。

DIEFFECT 型のうち使用するメンバは、エフェクトの種類によって異なる。コンスタント フォースは、単一のタイプ固有のパラメータのみを要求する、最も単純なフォースである。lGain、lDuration、および lTriggerButton の各メンバは、すべてのエフェクトに設定しなければならない。これらのメンバのデフォルト値はゼロであるが、通常は適切ではないためである。

デフォルトでは、エフェクトの方向は極座標で表される。つまり、DIEFFECT.x がフォースの来る方向を 100 分の 1 度単位で保持し、DIEFFECT.y はゼロでなければならない。

デバイスが満杯ではなく、排他協調レベルで取得されたなら、エフェクトは作成時にデバイスに自動的にダウンロードされる。


エフェクトの方向

Microsoft® DirectX® for Microsoft Visual Basic® は、x 軸と y 軸での 2 軸エフェクトをサポートしている。

エフェクトの方向は、エフェクトが来る方向である。y 軸の負側に沿った方向でのエフェクトは、スティックを y 軸の正側に沿って (ユーザーに向かって) 押そうとする。エフェクトを打ち消すためにユーザーがスティックを左方向に押さなければならない場合、このエフェクトは「左」方向である。つまり、このエフェクトは x 軸の負側にある。

方向は "極" 座標、"球面" 座標、または、"デカルト" 座標で表すことができる。デフォルトでは、極座標が使用される。方向は DIEFFECT 型の x メンバに指定される。この場合、y メンバは常にゼロである。デカルト座標を使用するには、lFlags メンバの DIEFF_CARTESIAN を指定して、x と y の両方を指定する必要がある。

極座標は、エフェクトに対して設定されたゼロポイント (真北) から時計回りに、実角度の 100 倍の単一角度で表される。通常これは負側の y 軸、すなわち、ユーザーから遠ざかる方向である。したがって、極座標 9,000 のエフェクトは通常、東の方向つまりユーザーの右側の方向を持つ。このエフェクトを打ち消すには、ユーザーは右側へ力を加えなければならない。

デカルト座標は 3 次元ベクトルに似ており、3 次元環境においてフォースをユーザーの向き設定に一致させる場合に非常に便利である。中心を始点 (0,0) とするグラフ用紙に直線を引くと、その直線の方向は、始点からの距離とは関係なく、交点の任意の座標により定義することができる。したがって、方向 (1, -2) と方向 (5, -10) はまったく同じものとなる。

注 : フォース フィードバック エフェクトの作成に使用する座標は方向のみを定義し、マグニチュードや距離は定義しない。

「エフェクトの作成」での例では、2 次元フォースの方向は極座標で定義される。この例ではフォースは南方向、すなわちユーザーの方向から来ているので、ユーザーがフォースを打ち消すにはスティックを手前に引き寄せなくてはならない。方向は北から時計回りに 180 度であり、次のように割り当てられている。effectInfo は有効な DIEFFECT 型である。

effectInfo.x = 18000

effectInfo.y メンバは 0 に設定しなければならず、デフォルトで 0 である。より明確にするために、割り当ては次のように表すこともできる。

effectInfo.x = 180 * DI_DEGREES

デカルト座標でこれと同じことを実現するにはどうしたらよいだろうか。lFlags メンバの DIEFF_CARTESIAN フラグを使用すると仮定すれば、次のように方向を指定することになる。

effectInfo.x = 0
effectInfo.y = 1

x の値が 0 である限り、y の値がどのような数値であっても、エフェクトは同じになる。指示されているのが方向だけで、マグニチュードが指示されていないからである。エフェクトの方向についての理論は、理解するのは難しいかもしれないが、実践してみればかなり容易に理解できる。

次のコードは、DirectInputEffect オブジェクトの dieff で表されるフォースの方向を反転する例である。dieff は、グローバル DIEFFECT 型の effectinfo を使って作成済みである。

effectInfo.lFlags = DIEFF_CARTESIAN
effectInfo.X = effectInfo.X * -1
effectInfo.Y = effectInfo.Y * -1
Call dieff.SetParameters(effectInfo, DIEP_DIRECTION)

その他のサンプル コードについては、「エフェクト方向設定の実例」を参照すること。


エフェクト方向設定の実例

デカルト座標での単一軸エフェクト

単一軸エフェクトの方向の設定は、軸の方向だけを指定すればよいので、単純である。DIEFFECT 構造体の lFlags メンバに DIEFF_CARTESIAN フラグを設定し、エフェクトが来る方向に応じて、x または y メンバを 1 か -1 に設定する。

次のコードは、右から左の方向への x 軸エフェクトを設定する例である。

Dim eff As DIEFFECT

eff.lFlags = DIEFF_CARTESIAN Or DIEFF_OBJECTOFFSETS
eff.x = 1
eff.y = 0

極座標での単一軸エフェクト

極座標を使って同じエフェクトを簡単に設定することもできる。DIEFFECT 構造体の lFlags メンバに DIEFF_POLAR フラグを設定し、x メンバを 0、90、180、270 度のいずれかに設定する。

次のコードは、前の例に示したのと同じ x 軸エフェクトを設定する例である。

Dim eff As DIEFFECT

eff.lFlags = DIEFF_POLAR Or DIEFF_OBJECTOFFSETS
eff.x = 90 * DI_DEGREES
eff.y = 0

極座標での 2 軸エフェクト

極座標 2 軸エフェクトの方向の設定は、極座標単一軸エフェクトの場合と同じである。唯一異なるのは、実角度の値の範囲が 4 軸の値に制限されないことである。

次のコードは、ユーザーの右上を始点とするエフェクトを設定する例である。

Dim eff As DIEFFECT

eff.lFlags = DIEFF_POLAR Or DIEFF_OBJECTOFFSETS
eff.x = 45 * DI_DEGREES
eff.y = 0

デカルト座標での 2 軸エフェクト

デカルト座標 2 軸エフェクトの方向の設定も単純である。まず、lFlags に DIEFF_CARTESIAN フラグを設定する。x メンバと y メンバには、そのポイントと始点 (0,0) を通る方向の線上にある任意のポイントの x 座標と y 座標が格納される。

次のコードは、前の例に示したのと同じエフェクトを設定する例である。

Dim eff As DIEFFECT

eff.lFlags = DIEFF_CARTESIAN Or DIEFF_OBJECTOFFSETS
eff.x = 1
eff.y = 2


エンベロープとオフセット

エンベロープ とオフセットを使って、いくつかの基本的マグニチュードを変更することができる。概要については、「フォース フィードバックの基本概念」を参照すること。

エフェクトの作成または変更の際にエンベロープを適用するには、DIEFFECT 型の bUseEnvelope メンバを TRUE に設定し、DIENVELOPE 型の envelope メンバを初期化する。

どのエフェクトがエンベロープをサポートするかを決定するのはデバイス ドライバである。通常は、コンスタント フォース、傾斜フォースおよび周期的フォースにエンベロープを適用できるが、条件には適用できない。特定のフォースがエンベロープをサポートするかどうかを判定するには、DirectInputEnumEffects.GetStaticParams メソッドを呼び出し、返された値の DIEP_ENVELOPE フラグをチェックする。

オフセットを適用するには、DIEFFECT の periodicForce、conditionX、または conditionY の各メンバで使用される、DIPERIODICFORCE 型または DICONDITION 型の lOffset メンバを設定する。周期的エフェクトの場合、オフセットの絶対値とエフェクトのマグニチュードを足した値が 10,000 を超えてはならない。

オフセットをコンスタント フォースや傾斜フォースに適用することはできない。コンスタント フォースや傾斜フォースの場合、マグニチュードを変更することによって同じエフェクトを発生させることができる。


エフェクトの再生

エフェクトの再生を開始する主な方法は 2 つある。DirectInputEffect.Start メソッドを呼び出して手動で開始する方法と、ボタン押下への応答で自動的に開始する方法である。DIEP_START フラグを指定して DirectInputEffect.SetParameters メソッドを呼び出すことでエフェクトを変更するときにも、再生が開始する。

Start メソッドの iterations パラメータに -1 を渡すと、エンベロープを適用しながらエフェクトの再生を反復させることができる。エンベロープを反復することなくエフェクトを反復したいとき (たとえば、最初に強いキックをした後、動悸を静めるというような場合) は、iterations に 1 を設定し、次に DIEFFECT 型の lDuration メンバに -1 を設定すればよい (これは DirectInputDevice8.CreateEffect メソッドに渡される型である)。

注 : デバイスによっては、エフェクトの複数回の補間が不可能で、Start メソッドへのパラメータ iterations に値 1 しか認めないものもある。

エフェクトをボタンに割り付けるには、DIEFFECT 型の lTriggerButton メンバを設定する。ボタンが押下されているときの再生間に遅延を加えたいならば、その遅延値を lTriggerRepeatInterval メンバに設定する。この遅延は、1 つの再生の終了から次の再生の開始までの間隔のことで、マイクロ秒単位で表される。

注 : デバイスによっては、複数回のエフェクトを同じボタンで発生させることができないものもある。2 つ以上のエフェクトを 1 つのボタンに割り付けると、最後にダウンロードされたエフェクトが、発生するエフェクトとなる。また、トリガの反復間隔はサポートされていない。

エフェクトのトリガ ボタンへの割り付けを解除するには、DirectInputEffect.Unload メソッドを呼び出すか、または、-1 に設定されている lTriggerButton にエフェクトのパラメータを設定するか、どちらかの操作を行わなければならない。

割り付けたエフェクトは、ほかのすべてのエフェクトと同様に、アプリケーションがデバイスへのアクセス権を失うと失われる。再びこれらのエフェクトを有効にするには、アプリケーションがデバイスを再取得すると同時にこれらのエフェクトをダウンロードする。この処理はトリガに割り付けていないエフェクトでは不必要である。なぜなら、この種のエフェクトは、Start メソッドが呼び出されるときはいつも、必要に応じて自動的にダウンロードされるからである。

エフェクトの継続時間が有限で、エフェクトが Start メソッドへの呼び出しによって開始する場合、継続時間が過ぎるとエフェクトの再生は終了する。エフェクトが継続的に再生するように指定されている場合、再生が終了するのは DirectInputEffect.Stop メソッドが呼び出されたときに限られる。トリガボタンに割り付けたエフェクトはそのボタンを押すと開始し、そのボタンを離すか、継続時間が過ぎるか、どちらか早い方の時点で終了する。


エフェクトのダウンロードとアンロード

エフェクトは再生する前にデバイスにダウンロードしなければならない。エフェクトのダウンロードとは、ドライバにエフェクトの再生の準備をするように通知することである。ダウンロードの方法を決定するのはまったくドライバに任せられる。一般に、ドライバはエフェクトのパラメータをハードウェア メモリに置き、デバイスとシステムの間のデータ順次転送を最小限に抑える。これにより、遅延時間が削減される。このことは、"発射" ボタンのように、トリガへの応答で機能する条件とエフェクトにとっては特に意味がある。デバイスが軸移動とボタン押下に応答するためにシステムとまったくやりとりを行う必要がない、というのが理想的だろう。

デバイスが満杯ではなくしかも排他協調レベルで取得されている場合には、エフェクトの作成時にダウンロードが自動的に行われる。エフェクトを開始、またはエフェクトのパラメータを変更するときも、ダウンロードはデフォルトで行われる。

パラメータを変更するときに DIEP_NODOWNLOAD フラグを指定すれば、引き続き DirectInputEffect.Download メソッドを使用してエフェクトのダウンロードやアップロードを行わなければならない。

デバイスが未取得状態のとき (たとえば、デバイスが排他フォアグラウンド協調レベルで取得されていて、アプリケーションがバックグラウンドに移行するとき)、エフェクトはアンロードされているので、アプリケーションがフォアグラウンドを再取得するときに再びエフェクトをダウンロードしなければならない。エフェクトのダウンロードは、DirectInputEffect.Start メソッドを呼び出すと自動的に行われる。しかし、デバイスを再取得すると同時にすべてのエフェクトをダウンロードするかどうかを選択することはできる。Start メソッドは通常トリガ ボタンに割り付けたエフェクトでは呼び出されないので、この種のエフェクトは必ずダウンロードする必要がある。

エフェクトのダウンロード中にアプリケーションが DIERR_DEVICEFULL エラーを受けたら、古いエフェクトをアンロードして新しいエフェクトのためのスペースを確保する必要がある。DirectInputEffect.Unload メソッドを呼び出せば、デバイスから 1 つのエフェクトを削除することができる。また、DirectInputDevice8.SendForceFeedbackCommand メソッドを呼び出してデバイスをリセットすれば、すべてのエフェクトを削除することもできる。

フォース フィードバック デバイスを生成すると、ハードウェアとドライバがリセットされるので、存在していたエフェクトすべてが消去される。


エフェクトの変更

エフェクトの再生中でもエフェクトのパラメータを変更することができる場合がある。これを行うには、DirectInputEffect.SetParameters メソッドを使用する。

エフェクトの再生中でも変更できるエフェクトのパラメータを調べるには、DirectInputEnumEffects.GetDynamicParams メソッドを呼び出す。

エフェクトの再生中には変更できないエフェクトのパラメータを変更しようとして、エフェクトが実際にまだ再生しているときは、通常、Microsoft® DirectInput® はエフェクトを停止させ、パラメータを更新し、エフェクトを再スタートさせる。この DirectInput のデフォルトの働きを無効にするには、SetParameters に DIEP_NORESTART フラグを渡せばよい。

次のコードは、DirectInputEffect オブジェクトの dieff で表されるコンスタント フォースのマグニチュードを変更する例である。このオブジェクトは、グローバルな DIEFFECT 型の effectinfo を使って作成済みである。

effectinfo.constantForce.lMagnitude = 5000
Call dieff.SetParameters(effectinfo, DIEP_TYPESPECIFICPARAMS)

注 : DIEFFECT の condition、constantforce、periodicforce、および rampforce の各メンバを変更する場合は、DIEP_TYPESPECIFICPARAMS フラグを設定する必要がある。


ゲイン

フォースを及ぼすデバイスの種類に応じて、エフェクトのフォースの大きさに差を付けたい場合があるだろう。たとえば、ある軸に対して最大 n ニュートンのフォースを生み出すデバイスでアプリケーションのエフェクトが正しく働くと思われるときは、より多くのフォースを生み出すデバイス用にゲインを調整したいことがあるだろう (軸のフォースの最大値を増やすためにゲインを使用することはできないので、生み出すフォースが小さいデバイスに対して、適切な値を基本的エフェクト マグニチュードに設定すべきである)。

また、ゲインを使って、ハードウェアで定義されたエフェクトのマグニチュードを減少させることもできる。

DirectInputDevice8.SetProperty メソッドを使用して、デバイス全体のゲインを設定することができる。

個別のエフェクトを作成するときは、DIEFFECT 型の lGain メンバに値を設定することで、エフェクトにゲインを設定しなければならない (lGain がゼロならば、そのエフェクトは感じられない)。この値は、flags パラメータに DIEP_GAIN を指定して DirectInputEffect.SetParameters を呼び出すことで、後から変更することができる。

デバイス ゲインを設定する目的は、アプリケーションにすべてのエフェクトのフォースを一括して制御させることである。たとえば、音響ミキサのメイン ボリューム コントローラのように、フォース フィードバック エフェクトに必要とされる強度をユーザーに指定させるスライダ コントロールをアプリケーションに付けたいと思うことがあるだろう。デバイス ゲインを設定すれば、ユーザーの好みに合わせて個別のエフェクトのゲインを、アプリケーションが調整する必要がなくなる。

1 つのゲイン値は 0 から 10,000 の範囲の値を取る。10,000 という値は、マグニチュードをスケーリングすべきでないということを示す。7,500 という値は、フォースの名目マグニチュードの 75% にフォースをスケーリングすべきであるということを意味している。その他の数値もこれに準じる。


フォース フィードバック状態

DirectInputDevice8.SendForceFeedbackCommand メソッドを使用すれば、デバイスのアクチュエータをオフ (再生しているエフェクトすべてを無視するのに有効) にし、エフェクトの再生を中断または中止し、デバイスをリセットしてダウンロードしたすべてのエフェクトを削除することができる。

現在のフォース フィードバック状態を取得するには、DirectInputDevice8.GetForceFeedbackState メソッドを使用する。このメソッドにより、アクチュエータが有効かどうか、再生が中断状態かどうか、およびデバイスがリセットされたかどうかという情報が返される。また、さまざまなスイッチに関する情報や、現在デバイスに電源が入っているかどうかの情報も取得される。


エフェクト オブジェクトの列挙

Microsoft® Visual Basic® では、作成したエフェクトの列挙はサポートされていない。


エフェクトのタイプ

ここでは、以下のフォース フィードバック エフェクト タイプについて説明する。

  • コンスタント フォース
  • 傾斜フォース
  • 周期的エフェクト
  • 条件
  • カスタム フォース
  • デバイス エフェクト


コンスタント フォース

コンスタント フォースは、一定のマグニチュードと継続時間を持つフォースのことである。

エンベロープをコンスタント フォースに適用して、フォースに形を与えることができる。たとえば、2,000 の名目マグニチュードと 2 秒の継続時間を持つエフェクトがあると仮定しよう。この場合、次の値を持つエンベロープを適用する。

パラメータ | 値
アタック時間 | 0.5 秒
初期アタック レベル | 5,000
フェード時間 | 1 秒
フェード レベル | 0

エフェクトを再生すると、次の値が得られる。

経過時間 | マグニチュード
0.0 | 5,000
0.1 | 4,400
0.2 | 3,800
0.3 | 3,200
0.4 | 2,600
0.5 | 2,000
(保持の継続時間) | 2,000
1.0: | 2,000
1.1 | 1,800
1.2 | 1,600
1.3 | 1,400
1.4 | 1,200
1.5 | 1,000
1.6 | 800
1.7 | 600
1.8 | 400
1.9 | 200
2.0 | 0

コンスタント フォースにオフセットを適用することはできない。

コンスタント フォースを生成するには、GUID_ConstantForce を DirectInputDevice8.CreateEffect メソッドに渡す。DirectInputEnumEffects.GetType により返された値の下位バイトが DIEFT_CONSTANTFORCE に等しい場合は、DirectInputEnumEffects.GetEffectGuid メソッドにより取得されたほかの任意の GUID を渡すこともできる。この方法を使えば、騒乱をシミュレーションする "コンスタント" フォース (名前は "コンスタント (定常)" だが実際にはマグニチュードがランダムに変化する) など、業者が設計したハードウェア特有のフォースを使用することができる。

コンスタント フォースのマグニチュードは、DIEFFECT の constantForce メンバ内の DICONSTANTFORCE 型に格納される。負のマグニチュードには、フォースの方向を反転するエフェクトがある。


傾斜フォース

傾斜フォースは、定義済みの初期マグニチュードと終期マグニチュードおよび有限の継続時間を持つフォースのことである。傾斜フォースは、1 方向だけに延びる場合も、あるいは 1 方向に向かって強い勢いで始まり、弱まって、停止し、反対方向に強く進むという場合もある。

次の図は、マグニチュード -5,000 で始まり、マグニチュード 5,000 で終わる傾斜フォースを表している。

エンベロープ を傾斜フォースに適用して、傾斜フォースを引き伸ばすことができる。次の図は、前の図の傾斜フォースにエンベロープ (緑で表してある) を適用するエフェクトを表している。

エンベロープの維持期間部分では、エフェクトのマグニチュードはエンベロープの適用前と同じ直線を描くことに注意する。アタック と フェードの継続時間については、傾斜フォースの傾斜はアタック レベルとフェード レベルで変更される。

傾斜フォースにはオフセットを適用できない。

傾斜フォースを生成するには、GUID_RampForce を DirectInputDevice8.CreateEffect メソッドに渡す。DirectInputEnumEffects.GetType により返された値の下位バイトが DIEFT_RAMPFORCE と等しい場合は、DirectInputEnumEffects.GetEffectGuid メソッドで取得されたほかの任意の GUID を渡すこともできる。この方法を使えば、業者が設計したハードウェア特有の傾斜フォースを使用することができる。

フォースの初期マグニチュードと終期マグニチュードは、DIEFFECT の rampForce メンバに含まれる DIRAMPFORCE 型で定義される。継続時間を無限にすることはできないので、DIEFFECT.lDuration は正の値でなければならない。


周期的エフェクト

周期的エフェクトは波形エフェクトである。Microsoft® DirectInput® では、以下の波形を定義している。

  • 正方形
  • サイン カーブ
  • コサイン カーブ
  • 三角形
  • アップ鋸歯 (SawtoothUp) － この波形は最大の正フォースに達した後、垂直に下降する。フォース フィードバックの基本概念」の例を参照すること。
  • ダウン鋸歯 (SawtoothDown) － この波形は最大の負フォースに達した後、垂直に上昇する。

周期的エフェクトにはエンベロープを適用することができる。「フォース フィードバックの基本概念」の例を参照すること。

周期的エフェクトのフェーズとは、エフェクトが始まる波形上のポイントである。フェーズは 0 から 35,999 までの範囲で、実角度の 100 倍で計測される。次の表は、選択したフェーズ値 (度単位) がさまざまな波形上のどこにあるかを示している。Max は波の最上部 (+) または最底部 (-) であり、Mid は波の中間ポイントである。これらの位置では、どちらの方向にもフォースは適用されていない。

波形 | 0 | 90 | 180 | 270
正方形 | +Max | +Max | -Max | -Max
サイン カーブ | Mid | +Max | Mid | -Max
三角形 | +Max | Mid | -Max | Mid
アップ鋸歯 | -Max | -Max/2 | Mid | +Max/2 (サイクルの反復の直前に +Max に達する)
ダウン鋸歯 | +Max | +Max/2 | Mid | -Max/2 (サイクルの反復の直前に -Max に達する)

ドライバにより、フェーズ値が直近のサポート値に丸められることがある。たとえば、ドライバによっては、サインエフェクトで 0 と 9,000 (コサインを生成するために) しかサポートせず、その他のエフェクトで 0 と 18,000 しかサポートしていないこともある。

周期的フォースを生成するには、DirectInputDevice8.CreateEffect メソッドの guid パラメータに、次に挙げる値のどれか 1 つを渡す。

  • GUID_Square
  • GUID_Sine
  • GUID_Triangle
  • GUID_SawtoothUp
  • GUID_SawtoothDown

DirectInputEnumEffects.GetType で返される値の下位バイトが DIEFT_PERIODIC に等しい場合は、DirectInputEnumEffects.GetEffectGuid メソッドで取得したほかの任意の GUID を渡すこともできる。この方法を使えば、業者が設計したハードウェア特有のフォースを使用することができる。

周期的エフェクトのタイプ固有パラメータは、DIEFFECT の periodicForce メンバに含まれる DIPERIODICFORCE 型に格納されている。

周期的エフェクトの周期 (DIEFFECT.periodic.lPeriod) とサンプリング間隔 (DIEFFECT.lSamplePeriod) を混同しないように注意すること。周期は 1 つの波のサイクル全体を実行するのに要する時間である。サンプリング間隔は、すべてのエフェクトと同様に、マグニチュードを実際に調整する間隔の最小時間である。


条件

条件とは、デバイス内の現在のセンサ値に反応して適用されるフォースのことである。すなわち、条件は、ジョイスティック ハンドルの位置または速度など、デバイスに関する情報を必要とする。

一般的に、条件はゲームやその他のアプリケーションにおける個別のイベントには関連付けられていない。条件は、フライト スティックの硬さや緩さ、または直進の位置に戻すハンドルの向きなどの状態を表現する。

条件は、定義されたマグニチュードを持たない。マグニチュードは、入力オブジェクトの動作と位置によって測定される。

Microsoft® DirectInput® は、次のような条件のエフェクトを定義する。

  • 摩擦 ― 軸が移動するときに適用されるフォースで、定義済みの摩擦係数によって決まる。
  • ダンパ ― このフォースはユーザーがジョイスティックを動かす速度に比例して増加する。
  • 慣性 ― このフォースは軸の加速度に比例して増加する。
  • スプリング ― このフォースは定義されている中立ポイントからの軸の距離に比例して増加する。

ほとんどのハードウェア デバイスでは、条件にエンベロープを適用できない。

条件には次のタイプのパラメータがある。

Offset
条件の適用が始まる適切なセンサ値を読み込む、ゼロからのオフセット。スプリング エフェクトでは、中立ポイント (スプリングが静止していると考えられる軸上のポイント) は条件用のこのオフセットによって定義される。ダンパ エフェクトでは、このオフセットにより、ダンパ フォースがゼロとなる最大速度値が定義される。通常、オフセットは慣性エフェクトや摩擦エフェクトには使用しない。
Coefficient
エフェクトのスケーリングを算出する乗数。デバイスによっては、条件に関係する軸上の正方向と負方向に別の係数を設定することができる。たとえば、攻撃を受けた飛行機をコントロールする操縦桿は、左よりも右へ動かす方が容易になるというような場合である。
Saturation
フォース フィードバックでは、飽和はエフェクトを上げる最大のフォースを表している。たとえば、操縦桿が X 軸上でスプリング条件を持っていると仮定してみよう。オフセットはゼロ、係数は 10,000 であり、通常は操縦桿が中立ポイントから最も離れているときに、最大フォースが発揮される。しかし、正負 5,000 の飽和を定義していると、操縦桿が右や左に移動した後、フォースは増加しない。

飽和をサポートしていないデバイスもある。

Deadband
デッドバンドとは、条件が作用しない軸のオフセット範囲のことである。スプリングが軸の中立ポイントに静止している場合は、デッドバンドはこの静止の範囲を拡張する。

デッドバンドをサポートしていないデバイスもある。

条件に継続時間を設定することができる。しかし、継続時間を INFINITE (-1) に設定し、アプリケーションで特定のイベントに応答するときだけエフェクトを停止する方法が使用されることが多い。

条件を生成するには、DirectInputDevice8.CreateEffect メソッドの rguid パラメータに、次に挙げる値のどれか 1 つを渡す。

  • GUID_Spring
  • GUID_Damper
  • GUID_Inertia
  • GUID_Friction

DirectInputEnumEffects.GetType により返された値の下位バイトが DIEFT_CONDITION に等しい場合は、DirectInputEnumEffects.GetEffectGuid メソッドで取得したほかの任意の GUID を渡すこともできる。この方法を使えば、業者が設計したハードウェア特有の条件を使用することができる。

条件のタイプ固有パラメータは、DIEFFECT 型の conditionX および conditionY メンバに含まれる DICONDITION 型に記述される。

エフェクトの係数と飽和について正と負の両方がデバイスでサポートされているかどうかを確認するには、アプリケーションで DirectInputEnumEffects.GetType メソッドを呼び出し、返された値のメンバを調べる必要がある。エフェクトが DIEFT_POSNEGCOEFFICIENTS フラグを返さなければ、DICONDITION.lNegativeCoefficient の値は無視され、lPositiveCoefficient の値が軸全体に適用される。同様に、エフェクトが DIEFT_POSNEGSATURATION フラグを返さなければ、lNegativeSaturation の値は無視され、lPositiveSaturation の値が負の飽和レベルとして使用される。また、エフェクトが DIEFT_SATURATION フラグを返さなければ、lPositiveSaturation と lNegativeSaturation の両方の値が無視され、飽和は適用されない。

係数には負数を設定することができる。こうすると、エフェクトは反対方向のフォースを生成する。たとえばスプリング エフェクトでは、係数に負数を設定すると、スプリング エフェクトはオフセット ポイントに向かって引っ張らずに、オフセット ポイントから離れる方向へ押すことになる。

また、GetType メンバ に DIEFT_DEADBAND フラグが設定されているかどうかをチェックすることで、デッドバンドが条件に対してサポートされているかどうかを知ることができる。サポートされていない場合、DICONDITION 構造体の lDeadBand メンバの値は無視される。

単一軸エフェクトを生成するには、DIEFFECT 型の conditionX メンバまたは conditionY メンバに、未使用の軸に対する係数をゼロとして設定する。

DirectX® for Microsoft Visual Basic® では、条件の回転はサポートされていない。


カスタム フォース

アプリケーションの作成者は、カスタム フォースを作成することによって、独自のエフェクトを作成することができる。カスタム フォースは、デバイスが再生するコンスタント フォース値の配列である。

カスタム フォースを生成するには、まずマグニチュードの配列を定義する。すべてのマグニチュードは -10,000 から 10,000 の範囲に含まれる。次に、この配列を DirectInputDevice8.CreateCustomEffect メソッドに渡す。

samplePeriod パラメータと、DIEFFECT 型の lSamplePeriod メンバに同じ値を設定する。この値はミリ秒単位の時間であり、フォースの配列の各要素が再生される時間を表す。

DIEFFECT.lDuration に設定された時間が過ぎるまで、カスタム フォースは繰り返し働く。


デバイス エフェクト

ハードウェア ドライバは、Microsoft® DirectInput® が定義するカテゴリに当てはまらない特殊効果をサポートすることができる。このようなエフェクトに対応するタイプ固有のパラメータは、ハードコーディングされていることもあれば、アプリケーションで変更できることもある。

Microsoft® DirectX® for Microsoft Visual Basic® は、カスタムのタイプ固有パラメータを要求するハードウェア エフェクトをサポートしていない。

ハードウェア ベンダーは、デバイス固有のエフェクトを識別する GUID を提供しなければならない。次に、アプリケーションは、ほかのエフェクトと同様に、DIEFFECT 型を初期化しなければならない。次に、この型を GUID と共に DirectInputDevice8.CreateEffect メソッドに渡す。

DirectInputEnumEffects 列挙にデバイス固有のエフェクトについての情報が入るが、DirectInputEnumEffects.GetType の戻り値の下位バイトは、定義済みの DirectInput のエフェクト タイプ (コンスタント フォース、傾斜フォース、周期的エフェクト、条件) のどれにデバイス エフェクトが分類されるのかを示している。定義済みのカテゴリのどれにも分類できない場合、下位バイトの値は DIEFT_HARDWARE である。

デバイス固有のエフェクトが定義済みのいずれかの種類に分類できれば、そのカテゴリの標準フォースの場合と同様に、DIEFFECT 型を初期化しなければならない。たとえば、エフェクト タイプが DIEFT_CONSTANTFORCE である場合は、constantForce メンバを初期化する必要がある。

DirectInput は確認のため、GUID と DIEFFECT 型をデバイス ドライバに渡す。GUID が未知である場合、デバイスは DIERR_DEVICENOTREG を返す。GUID は既知でも、タイプ固有データがそのエフェクトに対して不正確である場合は、デバイスは DIERR_INVALIDPARAM を返す。


プログラミングのヒントとツール

このセクションでは、特殊なプログラミング トピックと、Microsoft® DirectX® SDK 付属ツールの概要について説明する。この情報は、DirectInput® データの理解と、フォース フィードバック エフェクトの設計に役立つ。

以下のトピックに分けて、説明する。

  • 前バージョンの DirectInput 用の設計
  • デバッグ時の応答遅延の防止
  • Force Editor


前バージョンの DirectInput 用の設計

Microsoft® DirectX® 7 以前では Microsoft Visual Basic® をサポートした唯一のバージョンである DirectX 7 用に設計を行う場合は、DirectX 7 for Visual Basic タイプ ライブラリをインクルードする必要がある。詳細については、DirectX 7 のドキュメントを参照すること。


デバッグ時の応答遅延の防止

Microsoft Windows® 2000 のもと、Microsoft® DirectInput® でキーボードまたはマウスを使用する場合、デバッグ セッション中にコードを実行すると短期間の遅延が発生する場合がある。この現象はデバック モードでのみ発生する。実際のアプリケーションでは発生しない。ただし、Emulation 値を次のレジストリ キーに追加することで、デバック モードでもこの遅延が発生しないようにすることができる。

HKEY_LOCAL_MACHINE
    SOFTWARE
        Microsoft
            DirectInput

名前 | 型 | データ
Emulation | DWORD | 0x08 (マウス用) 0x10 (キーボード用) 0x18 (マウスおよびキーボード用)

これらの値を設定すると、DirectInput がデータを返す方法を変更することなく、遅延に影響されないエミュレーション モードを起動することができる。Microsoft Software Development Kit (SDK) には、Mouse and Keyboard Emulation On.reg および Mouse and Keyboard Emulation Off.reg の 2 つのレジストリ ファイルが付属していて、遅延に影響されないエミュレーション モードの起動と終了を指定することができる。これらのファイルは、(SDK ルート)\Samples\Multimedia\DirectInput\Bin に保存されている。

注 : Emulation 値は、デバイスがデバッグ モードの排他フォアグラウンド協調レベルで使用されている場合にのみサポートされる。


Force Editor

説明

Force Editor アプリケーションを使うと、フォース フィードバック エフェクトをデザインしたり、そのエフェクトを単独でテストしたり、いくつかのエフェクトを組み合わせてテストしたりすることができる。エフェクトは、ファイルに保存して、Microsoft® DirectInput® アプリケーションに読み込ませることができる。

パス

実行可能ファイル :(SDK ルート)\Bin\Dxutils\Fedit.exe

ユーザーズ ガイド

Force Editor には専用のドキュメントが添付している。Fedit.exe を起動し、F1 キーを押すとオンライン ヘルプを参照することができる。以下のファイルをダブルクリックして、オンライン ヘルプを直接起動することもできる。

(SDK ルート)\Bin\Dxutils\Fedit.chm


DirectInput Visual Basic チュートリアル

ここでは、次のチュートリアルを使用して、Microsoft Visual Basic® アプリケーションに Microsoft® DirectInput® を実装する方法を段階を追って説明する。

  • チュートリアル 1 : キーボードの使い方

    最初のチュートリアルは、イベント ポーリングを使って、既存のアプリケーションに DirectInput キーボード サポートを追加する手順を示す。

  • チュートリアル 2 : マウスの使い方

    2 番目のチュートリアルは、排他協調レベルとイベント通知を使って、アプリケーションで DirectInput マウス サポートを実現する手順を示す。このチュートリアルは、ScrawlB サンプルを基本としており、バッファリング データに焦点を当てる。

  • チュートリアル 3 : ジョイスティックの使い方

    このチュートリアルは、システムに接続されているジョイスティックをすべて列挙する方法、コールバック関数で各ジョイスティックに対する DirectInputDevice オブジェクトを作成して初期化する方法、および直接データを取得する方法を示す。

  • チュートリアル 4 : フォース フィードバックの使い方

    最後のチュートリアルでは、アプリケーションに簡単なフォース フィードバック エフェクトを実装する方法を示す。

  • チュートリアル 5 : アクション マッピングの使い方」

    最後のチュートリアルは、DirectInput の新しいアクション マッピング機能の設定、適用、使用について説明する。


チュートリアル 1 : キーボードの使い方

キーボード入力の準備を行うには、まず、DirectInput8 オブジェクトを作成する。次に、キーボードを表す DirectInputDevice8 オブジェクトを作成する。デバイスの動作を設定したり、データを取得したりするには、DirectInputDevice8 クラスのメソッドを使用する。

このチュートリアルでは、必要なタスクを以下の手順に分割している。

  • ステップ 1 : DirectInput8 オブジェクトとキーボード デバイスの作成
  • ステップ 2 : キーボードのパラメータの設定
  • ステップ 3 : キーボードのアクセス権の取得
  • ステップ 4 : キーボードからの直接データの取得
  • ステップ 5 : DirectInput システムの終了


ステップ 1 : DirectInput8 オブジェクトとキーボード デバイスの作成

Microsoft® DirectInput® システムを設定する際の最初の手順は、全体を管理する単一の DirectInput オブジェクトを作成することである。これは、DirectX8.DirectInputCreate メソッドを呼び出すことにより実現される。このメソッドは通常、メイン フォームの Load イベントか、Sub Main の中で次のように呼び出す。

Dim dx As New DirectX8
Dim di As DirectInput8

Set di = dx.DirectInputCreate()

次に、DirectInput8.CreateDevice にキーボード GUID を渡し、キーボードを標準デバイスとして作成する。

Dim didev As DirectInputDevice8
Set didev = di.CreateDevice("GUID_SysKeyboard")

キーボード デバイスが作成されたら、そのメソッドを使って、「ステップ 2 : キーボードのパラメータの設定」でデータ形式と協調レベルを設定する。


ステップ 2 : キーボードのパラメータの設定

DirectInputDevice8 を作成したら、デバイスのデータ形式を設定しなければならない。キーボードの場合は、その他の標準デバイスと同様に、非常に簡単なタスクである。DirectInputDevice8.SetCommonDataFormat メソッドを呼び出し、定数 DIFORMAT_KEYBOARD をパラメータとして使用して、Microsoft® DirectInput® が提供するデータ形式を指定する。バッファリング データを取得する場合でも、データ形式は設定しなければならない。

Call didev.SetCommonDataFormat(DIFORMAT_KEYBOARD)

DirectInput では、データ形式内のオフセットでデバイス オブジェクトを識別する。キーボードの場合、キーは DIKEYBOARDSTATE 型内のオフセットで識別される。

アプリケーションは、キーボードへのアクセス権を取得する前に、次のように DirectInputDevice8.SetCooperativeLevel メソッドを使用してデバイスの動作を設定しなければならない。

didev.SetCooperativeLevel Me.hWnd, _
        DISCL_NONEXCLUSIVE Or DISCL_BACKGROUND

このメソッドは、デバイスに関連付けられたウィンドウのハンドルと、必要な協調レベルを示す 2 つのフラグ (DISCL_EXCLUSIVE と DISCL_NONEXCLUSIVE のいずれか、および DISCL_FOREGROUND と DISCL_BACKGROUND のいずれか) を受け取る。ただし、DirectInput はキーボード デバイスへの排他アクセスをサポートしないため、この例のように、キーボードでは常に DISCL_NONEXCLUSIVE フラグを使用する必要がある。

また、この例ではバックグラウンド協調レベルを設定し、フォームがフォアグラウンドにあるかどうかにかかわらず入力を受け付けるようにしている。キー ストロークは引き続き、フォーカスを持つアプリケーションに渡されることに注意すること。大部分のアプリケーションはバックグラウンドにある間に入力を受け付ける必要はない。また、そのような場合には、DISCL_FOREGROUND フラグを設定するべきである。

キーボード デバイスの作成と設定が終了したら、それを取得する必要がある。その方法については「ステップ 3 : キーボードのアクセス権の取得」で説明する。


ステップ 3 : キーボードのアクセス権の取得

キーボードの動作を設定し終えたら、DirectInputDevice8.Acquire メソッドを呼び出すことでデバイスへのアクセス権を取得できる。アプリケーションは、デバイスからデータを取得する前に、デバイスを取得しなければならない。Acquire メソッドはパラメータを取らない。

Call didev.Acquire

サンプル コードでは、アプリケーションはバックグラウンドの非排他協調レベルを使用しているので、キーボードの取得に失敗したり、後でアクセスを喪失したりする可能性はない。ただし通常は、Acquire を呼び出す場合も、データを取得しようとする際と同様に、エラー処理を行うのが好ましい。

次は、キーボードからのデータの受け取りを開始する。その方法については、「ステップ 4 : キーボードからの直接データの取得」で説明する。


ステップ 4 : キーボードからの直接データの取得

デバイスを取得すれば、アプリケーションは、デバイスからのデータの取得を開始できる。これを最も簡単に行う方法は、DirectInputDevice8.GetDeviceStateKeyboard メソッドを呼び出すことである。このメソッドは、呼び出し時の瞬間のデバイスの状態を取得する。

GetDeviceStateKeyboard メソッドは、単一のパラメータとして DIKEYBOARDSTATE 型を受け取る。このパラメータは単に、256 バイトの配列を含んでいる。

次のサンプル コードは、キーボードの状態を取得する例である。

Dim state As DIKEYBOARDSTATE
Call didev.GetDeviceStateKeyboard(state)

キーボードの現在の状態を取得した後、アプリケーションは、呼び出し時に押された特定のキーに応答することができる。バッファ中の各要素が 1 つのキーを表す。要素の上位ビットが 1 に設定されている場合、そのキーは、呼び出し時に押されていたことを示す。1 に設定されていない場合、キーは押されていない。あるキーの状態をチェックするには、CONST_DIKEYFLAGS 列挙の定数を使用して、そのキーに対するバッファのインデックスを作成する。

次のサンプル コードは、アプリケーションが矢印キーに応答して車を移動する方法を示している。

If state.Key(DIK_UP) And &H80 Then
  ' 車を上方向に移動する。
End If
if state.Key(DIK_DOWN) And &H80 Then
  ' 車を下方向に移動する。
End If
' 以下同様。

また、次のフォームを使用することもできる。

If state.Key(DIK_UP) Then
  ' 車を上方向に移動する。
End If

また、DIK_UP は単一のキーであり、専用の上向き矢印キーであることに注意する。DirectInput では、テンキー上の 8 つのキーを特異キーとして扱い、NUM LOCK が有効かどうかにかかわらず、同一の識別子が付与される。いずれかの矢印キーから入力を受け取るようにするには、次のようなコードを記述する必要がある。

If state.Key(DIK_UP) Or state.Key(DIK_NUMPAD8) Then
  ' 車を上方向に移動する。
End If


ステップ 5 : DirectInput システムの終了

アプリケーションを終了しようとするときは、すべての Microsoft® DirectInput® デバイスを解放する必要がある。これを行うには DirectInputDevice8.Unacquire メソッドを使用し、一般には、次のサンプル コードに示すように、Unload イベント ハンドラで行う。

Private Sub Form_Unload(Cancel As Integer)
    didev.Unacquire
End Sub


チュートリアル 2 : マウスの使い方

このチュートリアルでは、マウスを排他協調レベルで使用し、通知に応答してバッファリング データを取得する方法を示す。サンプル コードは、ScrawlB サンプルを基にしている。

このチュートリアルは、次のステップで構成されている。

  • ステップ 1 : マウスの設定
  • ステップ 2 : 通知の設定
  • ステップ 3 : マウスの排他アクセス権の管理
  • ステップ 4 : マウスからのバッファリング データの取得


ステップ 1 : マウスの設定

Microsoft® DirectInput® でマウスを使用するための設定の最初の手順は、「チュートリアル 1 : キーボードの使い方」で実行した手順とほぼ同じである。ScrawlB サンプルでは、Sub Main でいくつかのグローバル変数を宣言してから、次のように初期化を行う。

Public objDX As New DirectX8
Public objDI As DirectInput8
.
.
Set objDIDev = objDI.CreateDevice("guid_SysMouse")
Call objDIDev.SetCommonDataFormat(DIFORMAT_MOUSE)
Call objDIDev.SetCooperativeLevel(frmCanvas.hwnd, _
        DISCL_FOREGROUND Or DISCL_EXCLUSIVE)

キーボードの場合とは反対に、DirectInput はマウスを排他的に制御する。その結果、アプリケーションがマウスを取得した状態にある限り、Microsoft Windows® はマウス メッセージを生成したり、システム カーソルを表示したりしない。DISCL_EXCLUSIVE は DISCL_FOREGROUND と組み合わせなければならない。なぜなら、アプリケーションがフォーカスを失った場合、マウスへの排他アクセスを持つことができず、データを取得することもできないからである。

ScrawlB サンプル アプリケーションはマウスに対する全責務を引き継ぐので、専用カーソルの位置を追跡したり、マウスの動きに合わせてカーソルの移動をスケーリングしたりしなければならない。次のグローバル変数は、カーソル座標 (メインフォームの左上隅からの相対ピクセル数) と移動スケーリングの格納に使用する。

Public g_cursorx As Long
Public g_cursory As Long
Public g_Sensitivity

Sub Main で、バッファリング データを受け取ることができるように、DirectInputDevice8.SetProperty メソッドを使ってバッファ サイズを設定する。

Dim diProp As DIPROPLONG
diProp.lHow = DIPH_DEVICE
diProp.lObj = 0
diProp.lData = BufferSize    ' BufferSize は定数。

Call objDIDev.SetProperty("DIPROP_BUFFERSIZE", diProp)

次は、マウス イベントでデータ取得をトリガする方法について、「ステップ 2 : 通知の設定」で説明する。


ステップ 2 : 通知の設定

ScrawlB サンプル アプリケーションは、Sub Main でマウス入力をポーリングするのではなく、Microsoft® DirectInput® に依存して、マウス イベントが発生したときに必ずマウス入力を通知する。アプリケーションは初期化処理中にイベント ハンドルを取得し、そのハンドルを DirectInputDevice8.SetEventNotification に渡す。

Dim EventHandle As Long

EventHandle = objDX.CreateEvent(frmCanvas)
Call objDIDev.SetEventNotification(EventHandle)

これにより、DirectInput は DirectXEvent8 クラスを実装するすべてのオブジェクトを通知する。ScrawlB の場合、実装するオブジェクトは frmCanvas フォームであり、その宣言セクションには次の行が含まれる。

Implements DirectXEvent8

この行により、frmCanvas は DirectXEvent8 クラスのメソッドを継承する。このクラスによって実装されるメソッドは DirectXEvent8.DXCallback のみであり、継承クラスはこのメソッドを実装しなければならない。入力イベントが送信されると、必ず DirectInput がこのメソッドを呼び出す。

DXCallback の実装については、「ステップ 4 : マウスからのバッファリング データの取得」で説明する。

排他アクセス レベルの維持には、責任が伴う。それについては、「ステップ 3 : マウスの排他アクセス権の管理」で説明する。


ステップ 3 : マウスの排他アクセス権の管理

ScrawlB サンプルでは、排他フォアグラウンド協調レベルでマウスを使用する方法を示す。このレベルでは、マウスがアプリケーションに取得されている間、Microsoft® Windows® はマウスを追跡しない。その場合、アプリケーションには主に、次の 3 つの重要な役割がある。

  • カーソルが必要な場合はカーソルを表示し、Microsoft DirectInput® データに応答して適切な速度でカーソルを移動しなければならない。
  • ユーザーがキーボードを使って別のアプリケーションに切り替えると取得は失われる。ユーザーがこのアプリケーションに戻したときに、マウスを再取得しなければならない。
  • アプリケーション内のメニューを操作するなど、ユーザーがシステム カーソルを使用したいときに、Windows がマウスを取得できる手段を提供しなければならない。

ScrawlB は、ユーザー定義の感度値により調整されたマウス移動の専用レコードを保持し、描画用カーソルとして機能するアイコンを表示することで、第 1 の役割を処理する。

ScrawlB は、アプリケーション ウィンドウがバックグラウンドに移行すると、必ずマウスは解放される。アプリケーションがフォアグラウンドに戻ると、アプリケーションは MouseMove イベント ハンドラの中で DirectInputDevice8.Acquire を呼び出すことで、マウスを自動的に再取得する。このハンドラは、Windows がマウス メッセージをアプリケーションに送信するときに呼び出される。この処理は、システム カーソルがクライアント ウィンドウ上に移動するか、クライアント ウィンドウがシステム カーソルの下のフォーカスを取得すると、発生する。ScrawlB がマウスを再取得した後は、当然ながら Windows マウス メッセージは送信されないので、これ以降のマウス イベントに応答して Form_MouseMove メソッドが呼び出されることはない。

ユーザーがショートカット メニューを操作したり、またはウィンドウのサイズを変更するなど、ほかの目的のためにシステム カーソルを表示したりできるように、ユーザーがメニューを表示すると、ScrawlB は DirectInputDevice8Unacquire メソッドを呼び出す。メニューが閉じられると、Form_MouseMove が呼び出され、マウスが再取得される。ただし、ユーザーがメニューから [Suspend] を選択する場合を除く。この場合はフラグが設定される。このフラグは、Form_MouseMove によるマウスの再取得を妨害するので、ユーザーはシステム カーソルを引き続き使用できる。

サンプル アプリケーションでは、マウスを解放する複数の方法を示している。ユーザーが Alt キーを押しながらスペース キーを押して、システム メニューを表示する場合、Windows は WM_ENTERMENULOOP メッセージを送信する。このメッセージは、サブクラス化されたウィンドウ プロシージャによりインターセプトされるので、マウスは取得されない。メニューを操作するためやユーザーがウィンドウのサイズを変更するために Windows がシステム カーソルを使用している限り、Windows は frmCanvas に対してマウス メッセージを送信しない。したがって、アプリケーションは Form_MouseMove でマウスを再取得しようとはしない。WM_ACTIVATE や WM_ACTIVATEAPP など、ほかの Windows メッセージを傍受する際にも同様の方法が使用される。これによりアプリケーションは、フォーカスの取得と喪失に応答して、マウスの取得と解放を完全に制御できる。

次は、「ステップ 4 : マウスからのバッファリング データの取得」でマウスからのデータを取得する。


ステップ 4 : マウスからのバッファリング データの取得

ScrawlB サンプルは、frmCanvas により実装される DirectXEvent8.DXCallback メソッド内部で、マウスのバッファリング データを取得する。入力イベントが発生すると必ずこのメソッドが呼び出される。

このメソッドは、Microsoft® DirectInput® がデータの格納に使用するバッファと同じサイズのバッファを宣言する。これは、以前の DirectInputDevice8.SetProperty の呼び出しにより設定されたサイズである。

Dim diDeviceData(1 To BufferSize) As DIDEVICEOBJECTDATA

また、実際に取得された項目数を受け取る変数、ループ カウンタ、およびイベントの前回のシーケンス番号を追跡する変数も必要である。

Dim NumItems As Integer
Dim i As Integer
Static OldSequence As Long

この時点でアプリケーションは、DirectInputDevice8.GetDeviceData を一度呼び出すことで、利用可能なデータをすべて取得する。

On Error GoTo INPUTLOST
NumItems = objDIDev.GetDeviceData(diDeviceData, 0)
On Error GoTo 0

エラー トラップに注意してほしい。DirectInput が送信するイベントの 1 つは、取得の喪失である。たとえば、ユーザーが別のアプリケーションに切り替えた場合、ScrawlB はマウスを取得した状態にはない。イベントが送信され、GetDeviceData が呼び出されても、データは取得状態にあるデバイスからしか取得できないため、このメソッドは失敗する。

ここでアプリケーションは、取得した項目を補間し、DIDEVICEOBJECTDATA 型内のデータを調べ、lOfs メンバと目的のさまざまなボタンと軸を表す定数を比較する。たとえば x 軸の場合、アプリケーションは lData メンバから軸位置の変化量を取得し、ユーザー定義の感度を計算しながら、これを使ってカーソル位置を調整する。これを次のサンプル コードに示す。

For i = 1 To NumItems
    Select Case diDeviceData(i).lOfs
        Case DIMOFS_X
            g_cursorx = g_cursorx + diDeviceData(i).lData * _
                g_Sensitivity

また、アプリケーションはシーケンス番号を調べて、前回の番号と比較する。2 つの軸イベントのシーケンス番号が同一の場合、マウスは斜めに移動している。階段エフェクトの発生を防ぐには、両方の軸の移動量が計算されるまで、カーソル位置の更新や線の描画を行わない方がよい。

            If OldSequence <> diDeviceData(i).lSequence Then
                UpdateCursor
                OldSequence = diDeviceData(i).lSequence
            Else
                OldSequence = 0
            End If

ボタンの場合、メソッドは、lData 内の適切なビットをチェックして、イベントの種類を判断する。ビットが設定されている場合、マウス ボタンは押されている。それ以外の場合、マウス ボタンは押されていない。GetDeviceData はデバイスの現在の状態を返すものではないので、ボタンが押し下げられているかどうかの専用記録を保持するのは、アプリケーションが行わなければならない。左ボタンの場合、ScrawlB はこの情報を変数 Drawing に保持する。

        Case DIMOFS_BUTTON0
            If diDeviceData(i).lData And &H80 Then
                Drawing = True

                ' Line 関数のレコードを保持する。
                CurrentX = g_cursorx
                CurrentY = g_cursory

                ' ボタンがすぐに上がった場合はポイントを描画する。
                PSet (g_cursorx, g_cursory)
            Else
                Drawing = False
            End If
.
.
    End Select
Next i


チュートリアル 3 : ジョイスティックの使い方

このチュートリアルでは、ジョイスティック デバイスの作成方法、ジョイスティックのプロパティの設定方法、および直接データの取得方法を示す。この例は、Joystick サンプルを基にしている。

このチュートリアルでは、必要なタスクを以下の手順に分割している。

  • ステップ 1 : デバイスの列挙とジョイスティックの作成
  • ステップ 2 : ジョイスティックの能力の取得
  • ステップ 3 : ジョイスティックのプロパティの設定
  • ステップ 4 : ジョイスティックからの直接データの取得


ステップ 1 : デバイスの列挙とジョイスティックの作成

システム キーボードやシステム マウスと同じ意味でのシステム ジョイスティックというものはなく、ジョイスティックの DirectInputDevice8 オブジェクトを作成するには、まずインスタンス GUID (グローバル ユニーク識別子) を取得する必要がある。通常、これは利用可能なジョイスティックを列挙し、ユーザーに選択肢を提示して、選択されたデバイスの情報を取得することにより実現される。

すべてのデバイスと同様に、最初に DirectInput システムを作成する必要がある。

Dim dx As New DirectX8
Dim di As DirectInput8

Set di = dx.DirectInputCreate()

次の手順では、DirectInput8.GetDIDevices メソッドを使ってデバイスを列挙する。このメソッドのパラメータとして、アプリケーションがシステムにアタッチされているゲーム コントローラ デバイスだけを列挙するよう指示するフラグが渡される。列挙の結果は、DirectInputEnumDevices8 クラスのインスタンスに格納される。

Dim diDev As DirectInputDevice8
Dim diDevEnum As DirectInputEnumDevices8

Set diDevEnum = di.GetDIDevices( _
            DI8DEVCLASS_GAMECTRL, DIEDFL_ATTACHEDONLY)

列挙が終了し、最低 1 つのジョイスティックが検出されたと仮定すると、その情報を操作できる。Joystick サンプルの例では、デバイスがリスト ボックスに追加され、ユーザーはそこから選択することができる。DirectInputEnumDevices8.GetCount メソッドは、列挙に格納される項目数を指定する。

'アタッチされているジョイスティックをリスト ボックスに追加する。
Dim i As Integer
For i = 1 To diDevEnum.GetCount
    Call lstJoySticks.AddItem( _
        diDevEnum.GetItem(i).GetInstanceName)
Next

GetInstance はデバイスのわかりやすい名前を返す。

この時点で、Joystick サンプルはイベント ハンドラを初期化して、デバイスに関連付ける。この手順は、「ステップ 2 : ジョイスティックの能力の取得」の最後で使用する。

Dim EventHandle as Long
EventHandle = dx.CreateEvent(Me)

ユーザーがリストからジョイスティックを選択すると、そのデバイスが作成され、lstJoySticks_Click プロシージャ内で初期化される。システム キーボードやシステム マウスとは異なり、DirectInput8.CreateDevice に渡す標準 GUID がないため、デバイス インスタンスの GUID を DirectInputDeviceInstance8.GetGuidInstance メソッドを使って取り出す必要がある。Microsoft DirectX® for Microsoft Visual Basic® のすべての列挙コレクションと同様、デバイスの列挙は 1 がベースであることに注意する。したがって、インデックスはリスト ボックス内の選択項目のインデックスより 1 つ大きくなる。 また、リスト ボックスはソートしない。

Set diDev = di.CreateDevice(diDevEnum.GetItem( _
        lstJoySticks.ListIndex + 1).GetGuidInstance)

またジョイスティックは、協調レベルと形式に対して初期化する必要がある。この例では、DIFORMAT_JOYSTICK 形式が使用されている。さらにコントロールの種類が多いジョイスティックでは、もう 1 つの形式の DIFORMAT_JOYSTICK2 も使用することができる。

diDev.SetCommonDataFormat DIFORMAT_JOYSTICK
diDev.SetCooperativeLevel Me.hWnd, _
        DISCL_BACKGROUND Or DISCL_NONEXCLUSIVE

デバイス上のオブジェクトを列挙しようとしたり、プロパティを操作しようとしたりする前に、データ形式を設定する必要がある。

ジョイスティックが作成できたら、「ステップ 2 : ジョイスティックの能力の取得」でその能力を調べる。


ステップ 2 : ジョイスティックの能力の取得

デバイス上のボタン、軸、および視点コントローラについての情報を取得するには、DirectInputDevice8.GetCapabilities を呼び出すだけでよい。

Dim joyCaps As DIDEVCAPS
diDev.GetCapabilities joyCaps

Joystick サンプルが知る必要があるのは、デバイス上のボタンと視点コントローラの数のみである。DIDEVCAPS 型は、デバイス上の軸の数も報告するが、軸の状態については一切情報を公開しない。この情報を知るために、サンプルは独自の IdentifyAxes プロシージャを呼び出す。まず変数を宣言し、使用可能な軸の存在または不在を示すブール値を保持する配列を初期化する。

Sub IdentifyAxes(diDev As DirectInputDevice8)

    Dim didoEnum As DirectInputEnumDeviceObjects
    Dim dido As DirectInputDeviceObjectInstance
    Dim i As Integer

    For i = 1 To 8
        AxisPresent(i) = False
    Next

プロシージャは、デバイスのデバイス オブジェクトの列挙に進む。DIDFT_AXIS 値は、軸の列挙を制限する。

    Set didoEnum = diDev.GetDeviceObjectsEnum(DIDFT_AXIS)

DirectInputDevice8.SetCommonDataFormat の呼び出しで以前に設定されたデータ形式の中で、そのオフセットごとに DirectInputDeviceObjectInstance を問い合わせる。このオフセットにより、軸の従来の役割やタイプが識別される。たとえば、GUID_RzAxis は、メイン スティックのひねり動作に対応することがわかる。ただし、デバイス ドライバは、軸に対して自由に指示を割り当てることができる。ユーザーがアプリケーション内で軸とアクションの対応を変更できるようにしておくのは良いアイデアである。

    Dim sGuid as String
    For i = 1 To didoEnum.GetCount
        Set dido = didoEnum.GetItem(i)
        sGuid = didoEnum.GetItem(i)

        Select Case sGuid
            Case "GUID_Xaxis"
                AxisPresent(1) = True
            Case "GUID_Yaxis"
                AxisPresent(2) = True
' 以下同様。
.
.
.
        End Select
    Next
End Sub

次に、アプリケーションは、以前に作成されたイベント ハンドルをデバイスに渡す。これにより、入力イベントが発生すると、通知はフォームに送信される。

Call diDev.SetEventNotification(EventHandle)

次は、「ステップ 3 : ジョイスティックのプロパティの設定」でジョイスティックのプロパティを設定する。


ステップ 3 : ジョイスティックのプロパティの設定

プロパティの変更は、DirectInputDevice8.SetProperty メソッドを使って行う。これはデバイスの確立後、かつデバイスの取得前に行わなければならない。

デバイスが返す軸の範囲の値は軸ごとに異なっているので、すべてのデバイスに適用される範囲を設定するのが好ましい。Joystick サンプルでは、すべての軸の値を 0 ～ 10,000 の範囲に収めるよう要求している。

プロパティは、プロパティごとに異なる型を使って設定される。軸値に対しては、DIPROPRANGE 型を使用する。このプロパティ型の構造体は、SetProperty を呼び出して適用される。

Dim DiProp_Range As DIPROPRANGE

With DiProp_Range
    .lHow = DIPH_DEVICE
    .lMin = 0
    .lMax = 10000
End With
diDev.SetProperty "DIPROP_RANGE", DiProp_Range

DIPH_DEVICE フラグを使って、そのプロパティがデバイス上のすべての軸に適用されることを示す。Joystick サンプルでは、ジョイスティックのデッド ゾーンと飽和ゾーンも設定する。この例では、これらの値をスロットルやラダーなど、ほかの軸に設定することは望ましくない。プロパティ型の lHow メンバが設定されると、データ形式内のオフセットによって識別されるデバイス オブジェクトに対してプロパティの変更が適用されることを示し、lObj メンバはそのオフセット値に設定される。この例では、DIPROPLONG 型を使って、SetProperty によって Long 型の値が送信される。次のサンプル コードは、デッド ゾーン プロパティの場合を示している。

Dim DiProp_Dead As DIPROPLONG

With DiProp_Dead
    .lData = 1000
    .lHow = DIPH_BYOFFSET

' x 軸の設定。
    .lObj = DIJOFS_X
    diDev.SetProperty "DIPROP_DEADZONE", DiProp_Dead

' y 軸の設定。
    .lObj = DIJOFS_Y
    diDev.SetProperty "DIPROP_DEADZONE", DiProp_Dead
End With

lData の値は、無効ゾーンとして設定する移動範囲の割合であり、10,000 までの値で表される。1000 は 10,000 の 10 分の 1 であり、x 軸および y 軸の移動範囲のうち中心の 10 分の 1 を指定し、まだ中心にあることが報告される (この場合、5000)。

注 デッド ゾーンと飽和値は、デバイスにより報告される値の範囲にかかわらず、常に 10,000 までの値で表される。

デバイスの飽和ゾーンも同様に設定する。この場合、lData は飽和ゾーンの外側にある最大の移動範囲の割合を表すので、9500 である。つまり、ジョイスティックにより返される未処理の値の上位および下位 5% は、デバイスに設定された最小値または最大値として報告される (この場合、0 または 10,000)。

次に、「ステップ 4 : ジョイスティックからの直接データの取得」でデバイスからのデータを取得する。


ステップ 4 : ジョイスティックからの直接データの取得

この時点で、必要なプロパティは設定されており、デバイスは取得可能で、データはジョイスティックから収集可能である。Joystick サンプルでは、プロパティを設定した後のループ内でデバイスをポーリングしている。これには、DirectInputDevice8.Poll メソッドを使用する。実際のマルチメディア アプリケーションでは、ポーリングはメインのゲーム ループやレンダリング ループ内で行われる。

diDev.Acquire

While DoEvents
    diDev.Poll
Wend

サンプル アプリケーションは、実際にデバイスをポーリングするたびに直接データを取得しているわけではない。不要な画面更新をなくすために、ポーリングは通知に基づいて行われる。割り込みを生成しないデバイスにより通知が発行されていることを保証する唯一の方法は、Poll を呼び出すことである。ゲーム デバイス (HID など) によってはポーリングは必要ではないが、DirectInputDevice8.Poll を余分に呼び出すことは、Poll を呼び出す前にデバイスのフラグをチェックするのと同様に効率的である。

通知は DirectXEvent8.DXCallback メソッドの実装内で通常どおり処理される。このプロシージャが呼び出されるたびに、アプリケーションはジョイスティック イベントが発生したことを認識する。この時点で、DirectInputDevice8.GetDeviceData を呼び出して、待機中の軸の変化やボタン イベントを取得することもできる。ただし、ゲーム コントローラでは、デバイス全体の状態を取得するのが一般的である。したがってこのサンプルでは、コールバック関数から DirectInputDevice8.GetDeviceStateJoystick を呼び出して使用している。

Dim js As DIJOYSTATE

diDev.GetDeviceStateJoystick js

DIJOYSTATE 型の値には、ジョイスティック上のすべてのデバイス オブジェクトの状態が格納されている。「ステップ 2 : ジョイスティックの能力の取得」で、どのボタン、軸、視点コントローラが実際に存在するかを調べているので、型のどのメンバを無視するかも認識している。


チュートリアル 4 : フォース フィードバックの使い方

このチュートリアルでは、フォース フィードバック デバイスが存在するかどうかをテストする方法、エフェクトを生成して再生する方法、およびエフェクトの再生中にパラメータを変更する方法を示す。

このチュートリアルでは、タスクを以下の手順に分割している。

  • ステップ 1 : フォース フィードバック デバイスの初期化
  • ステップ 2 : デバイスのプロパティの設定
  • ステップ 3 : エフェクトの作成
  • ステップ 4 : エフェクトの変更


ステップ 1 : フォース フィードバック デバイスの初期化

フォース フィードバックを実装するには、まず、適切なデバイスが使用可能かどうかを調べ、使用可能であれば、そのデバイスに DirectInputDevice8 オブジェクトを作成しなければならない。このチュートリアルでは、アプリケーションは x 軸と y 軸の両方でエフェクトを再生できるデバイスを必要としていると仮定する。

次のサンプルは、通常どおり、DirectInput8 オブジェクトを作成し、そのオブジェクトを使って、DirectInputEnumDevices8 オブジェクト内で利用可能なデバイスを列挙することから始まっている。列挙対象は、DI8DEVTYPE_JOYSTICK 型のアタッチ済みデバイスに制限されている。

Dim dx As DirectX8
Dim di As DirectInput8

Dim diDev As DirectInputDevice8
Dim diEnumDev As DirectInputEnumDevices8
Dim diDevInst As DirectInputDeviceInstance8
Dim diDevObjEnum As DirectInputEnumDeviceObjects
Dim devobj As DirectInputDeviceObjectInstance

Dim devcaps As DIDEVCAPS
Dim ForceX As Boolean, ForceY As Boolean
Dim FoundForce As Boolean
Dim efftype As Long
Dim strObjGuid As String

Dim i As Integer, iAxes As Integer

Set di = dx.DirectInputCreate
Set diEnumDev = di.GetDIDevices(DI8DEVTYPE_JOYSTICK, _
                                          DIEDFL_ATTACHEDONLY)

ここで、サンプルはフォース フィードバック能力を持つデバイスを見つけるまで、使用可能なデバイスの調査を補間する。

For i = 1 To diEnumDev.GetCount
    Set diDevInst = diEnumDev.GetItem(i)
    Set diDev = di.CreateDevice(diDevInst.GetGuidInstance)
    Call diDev.GetCapabilities(devcaps)
    If devcaps.lFlags And DIDC_FORCEFEEDBACK Then
    'フォース フィードバック デバイスを処理する。

次に、X 軸と Y 軸の両方がフォース フィードバックをサポートする必要があるため、デバイス上のすべての軸が DirectInputEnumDeviceObjects コレクションに列挙される。

    Set diDevObjEnum = didev.GetDeviceObjectsEnum(DIDFT_AXIS)

存在する軸のコレクションを調べ、x 軸と y 軸を探し、それらの軸がフォース フィードバック エフェクトをサポートするかどうかを調べる。

    ForceX = False
    ForceY = False
    For iAxes = 1 To diDevObjEnum.GetCount
        Set devobj = diDevObjEnum.GetItem(iAxes)
        strObjGuid = devobj.GetGuidType
        If strObjGuid = "GUID_XAxis" Then
            If devobj.GetFlags And DIDOI_FFACTUATOR Then
                ForceX = True
            End If
        ElseIf strObjGuid = "GUID_YAxis" Then
            If devobj.GetFlags And DIDOI_FFACTUATOR Then
                ForceY = True
            End If
        End If
        FoundForce = ForceX And ForceY
        If FoundForce Then Exit For
    Next iAxes

Next i    '次のデバイス。

If Not FoundForce Then
    MsgBox "Two force feedback axes required."
End If

適切なデバイスが確認できたら、「ステップ 2 : デバイスのプロパティの設定」でデバイスのプロパテイを設定する。


ステップ 2 : デバイスのプロパティの設定

適切なフォース フィードバック デバイスが見つかった場合、能力をチェックするために前のステップで作成された DirectInputDevice8 オブジェクトが残っている。オブジェクトには、データ形式や協調レベルの設定、入力用の範囲プロパティの設定などの初期化が必要である。この処理については、「チュートリアル 3 : ジョイスティックの使い方」を参照すること。協調レベルには DISCL_EXCLUSIVE を含めなければならない。実際のアプリケーションではおそらくバックグラウンドでデバイスにアクセスする必要はないが、DISCL_BACKGROUND フラグは、デバッガのウィンドウに切り替えても取得を失わないため、デバッグ操作が簡単になる。

Call didev.SetCommonDataFormat(DIFORMAT_JOYSTICK2)
Call didev.SetCooperativeLevel(Me.hWnd, _
        DISCL_BACKGROUND Or DISCL_EXCLUSIVE)
' 範囲プロパティの設定などを行う。

フォース フィードバックの場合、デフォルトのスプリング アクションが生成するエフェクトに干渉しないように、デバイスの自動センタリング プロパティを無効にする方がよい場合が多い。これを行うには、DirectInputDevice8.SetProperty メソッドによって DIPROPLONG 型を送り、DIPROP_AUTOCENTER プロパティを 0 に設定する。

Dim prop As DIPROPLONG
prop.lData = 0
prop.lHow = DIPH_DEVICE
prop.lObj = 0
Call didev.SetProperty("DIPROP_AUTOCENTER", prop)

デバイスの構成が終わったら、構成を取得できる。

 didev.Acquire

フォース フィードバック デバイスの用意ができたら、使用するエフェクトを作成する。これについては、「ステップ 3 : エフェクトの作成」で説明する。


ステップ 3 : エフェクトの作成

このサンプルで作成するエフェクトは、静止オブジェクト (磁石など) が移動可能なオブジェクト (鉄球) を引き付ける力をシミュレートする。移動可能なオブジェクトはジョイスティックで制御される。このシミュレーションの最初に、鉄球は磁石の真南にあり、引く最大距離の半分の位置にある。

磁石の引き付ける力は、コンスタント フォースによってシミュレートする。まず、フォースを記述する DIEFFECT 型を設定する。

Dim EffectInfo as DIEFFECT
With EffectInfo
    .constantForce.lMagnitude = 5000
    .lDuration = -1       ' 無限。
    .x = 18000
    .lGain = 10000        ' 最大マグニチュードで再生する。
    .lTriggerButton = -1  ' トリガ ボタンなし。
End With

x パラメータを 18,000 に設定し、フォースが真北から 180 度の点から発生していると指定する。つまり、フォースは真南から真北に、ユーザーから遠くに向かって移動する。エフェクトの方向の詳細については、「エフェクトの方向」を参照すること。

DIEFFECT のほかのすべてのメンバは、コンスタント フォースに無関係であるか、または値 0 で有効である。

エフェクトが定義されたら、DirectInputDevice8.CreateEffect メソッドを使って作成する。

Dim di_effect As DirectInputEffect
Set di_effect = didev.CreateEffect("GUID_ConstantForce", EffectInfo)

このときにデバイスが取得状態にあれば、エフェクトが自動的にダウンロードされる。エフェクトが取得状態でない場合は、DirectInputEffect.Start メソッドを使ってエフェクトが開始されたときにダウンロードされる。

di_effect.Start(1, 0)

このエフェクトは無限の継続時間を持っているので、エフェクトは一度だけ補間すればよい。

変化しない一定のエフェクトも有用であるが、エフェクトは再生やユーザーからの入力に対応して変化することがある。これについては、「ステップ 4 : エフェクトの変更」で説明する。


ステップ 4 : エフェクトの変更

ユーザーがジョイスティックを使って鉄球を回転させるのに応じて、アプリケーションはエフェクトの方向とマグニチュードを調整する。しかし、まず最初に、そのデバイスがエフェクトを停止したり再スタートせずに、エフェクトの方向を変更することができるかどうかを調べる必要がある。Microsoft® DirectInput® は必要に応じてエフェクトの自動停止や自動再スタートを行うが、これを自分で行うことによって、滑らかな連続性がとぎれないようにすることができる。

エフェクトの機能を調べるには、まずサポートされているエフェクトを列挙する。これには DirectInputDevice8.GetEffectsEnum メソッドを使用して、DirectInputEnumEffects 型を解決する。DIEFT_CONSTANTFORCE フラグを使えば、サポートされているコンスタント フォース エフェクトのみを列挙できる。

Dim diEnumEffects As DirectInputEnumEffects
Set diEnumEffects = didev.GetEffectsEnum(DIEFT_CONSTANTFORCE)

次に目的のエフェクトの列挙を調べる。列挙されているエフェクトが基準を満たしている場合、DirectInputEnumEffects.GetDynamicParams メソッドを呼び出して、エフェクトのパラメータが停止や再スタートなく変更できるかどうかを調べる。GetDynamicParams によって返されるフラグを調べ、それを CONST_DIEPFLAGS の既知の値と比較する。次の例では、結果フラグを格納する変数 params が DIEP_DIRECTION と比較され、エフェクト実行中にエフェクトの方向を変更できることが確認されている。

Dim params As Long
Dim i As Long

For i = 1 To diEnumEffects.GetCount
    ' 標準のコンスタント フォースを探す。ほかの処理を行ってもよい。

    If diEnumEffects.GetEffectGuid(i) = "GUID_ConstantForce" Then
        params = diEnumEffects.GetDynamicParams(i)
        Exit For
    End If

Next i

If Not (params And DIEP_DIRECTION) Then
    ' 方向を動的に変えることはできない。変更対象のポイントを制限するなど、
    ' 補正のための措置をとる。
End If

同様に、エフェクトのマグニチュードを動的に変更できるかどうかを知るには、次のチェックを行う。

If Not (params And DIEP_TYPESPECIFICPARAMS)
   ' タイプ固有パラメータを動的には変更できない。
End If

アプリケーションは、デバイスが入力に対してポーリングされるたびにエフェクトを変更する。変更後のマグニチュードは CurrentMag に、変更後の方向 (度数) は CurrentBearing に格納されるものとする。必要な変更を加えるために、関連する DIEFFECT のメンバのみを初期化する必要がある。

EffectInfo.constantForce.lMagnitude = CurrentMag
EffectInfo.x = CurrentBearing * DI_DEGREES

ここで、どのメンバに有効なデータが含まれているかを示すフラグと共に、新しいデータを含む DIEFFECT 型を DirectInputEffect.SetParameters に渡す。

di_effect.SetParameters(EffectInfo, _
        DIEP_DIRECTION Or DIEP_TYPESPECIFICPARAMS)

DIEP_TYPESPECIFICPARAMS フラグは、そのエフェクトのタイプに関連する情報を含むメンバが有効であることを示す。コンスタント フォースの場合、これは constantForce メンバを意味する。


チュートリアル 5 : アクション マッピングの使い方

このチュートリアルでは、アクション マップの設定、修正、および適用について説明する。サンプル コードは、宇宙戦ゲームを想定して設計された ActionMapper サンプルに基づいている。

Microsoft® DirectInput® システムの設定の準備手順は、どのアプリケーションでも同じである。詳細については、ほかのチュートリアルを参照すること。サンプルでは、キーボード、マウス、およびジョイスティックのすべてが使用されているため、それぞれを設定する必要がある。

このチュートリアルでは、タスクを以下の手順に分割している。

  • ステップ 1 : ゲーム アクションの定義
  • ステップ 2 : アクション マップの定義
  • ステップ 3 : デバイスへのアクションのマッピング
  • ステップ 4 : アクション マップの構成と適用
  • ステップ 5 : アクション マップの表示
  • ステップ 6 : アクション マップのユーザー構成
  • ステップ 7 : アクション マッピングされたデータの取得


ステップ 1 : ゲーム アクションの定義

アクション マップ作成の最初の手順は、ゲーム アクションの定義である。これらのアクションはアプリケーション固有であり、開発者が定義する。ActionMapper サンプルでは、アクションは宇宙戦シミュレータとしての必要性を考えて選択されている。これらの値は、開発者が適切と思ういろいろな方法で定義できる。アクションは、アクション マップの準備の概要に示すように列挙として定義したり、ActionMapper サンプルのコードのように定数として定義することができる。

Const INPUT_LEFTRIGHT_AXIS = 1
Const INPUT_UPDOWN_AXIS = 2
Const INPUT_TURNLEFT = 4
Const INPUT_TURNRIGHT = 5
Const INPUT_FORWARDTHRUST = 6
Const INPUT_REVERSETHRUST = 7
Const INPUT_FIREWEAPONS = 8
Const INPUT_ENABLESHIELD = 9
Const INPUT_DISPLAYGAMEMENU = 10
Const INPUT_QUITGAME = 11

アクションの値を定義したら、それをジャンル固有のアクション マッピング定数に割り当てる。これについては、「ステップ 2 : アクション マップの定義」で説明する。


ステップ 2 : アクション マップの定義

次に、各ゲーム アクションを、1 つの仮想コントロールまたはデバイス オブジェクトに割り当てる。これらのコントロールはアクション マッピング定数として定義され、ジャンルおよびサブジャンルによって定義される。ActionMapper サンプルでは、フライト ゲーム ジャンルの宇宙戦サブジャンルを選択するのが適切である。このサブジャンルでは、以下の定数を使用できる。

優先順位 1 のコントロール

DIAXIS_SPACESIM_LATERAL
DIAXIS_SPACESIM_MOVE
DIAXIS_SPACESIM_THROTTLE
DIBUTTON_SPACESIM_FIRE
DIBUTTON_SPACESIM_MENU
DIBUTTON_SPACESIM_TARGET
DIBUTTON_SPACESIM_WEAPONS

優先順位 2 のコントロール

DIAXIS_SPACESIM_CLIMB
DIAXIS_SPACESIM_ROTATE
DIBUTTON_SPACESIM_BACKWARD_LINK
DIBUTTON_SPACESIM_DEVICE DIBUTTON_SPACESIM_DISPLAY
DIBUTTON_SPACESIM_FASTER_LINK
DIBUTTON_SPACESIM_FIRESECONDARY
DIBUTTON_SPACESIM_FORWARD_LINK
DIBUTTON_SPACESIM_GEAR
DIBUTTON_SPACESIM_GLANCE_DOWN_LINK
DIBUTTON_SPACESIM_GLANCE_LEFT_LINK
DIBUTTON_SPACESIM_GLANCE_RIGHT_LINK
DIBUTTON_SPACESIM_GLANCE_UP_LINK
DIBUTTON_SPACESIM_LEFT_LINK DIBUTTON_SPACESIM_LOWER
DIBUTTON_SPACESIM_PAUSE DIBUTTON_SPACESIM_RAISE
DIBUTTON_SPACESIM_RIGHT_LINK
DIBUTTON_SPACESIM_SLOWER_LINK
DIBUTTON_SPACESIM_TURN_LEFT_LINK
DIBUTTON_SPACESIM_TURN_RIGHT_LINK
DIBUTTON_SPACESIM_VIEW
DIHATSWITCH_SPACESIM_GLANCE

優先順位 1 のコントロールは最低限必要なコントロールで、できるだけデバイス オブジェトにマッピングする必要がある。優先順位 2 のコントロールは、基本的なゲーム操作にはそれほど重要ではなく、必要に応じてマッピングできる。

ゲーム アクションは、DIACTION 型の配列にあるアクション マッピング定数コントロールに割り当てられる。各 DIACTION 型は、最低 1 つのゲーム アクションと、それに関連するアクション マッピング定数、必要なフラグ、そして、アクションのわかりやすい名前を格納する。残りの DIACTION メンバは、この時点では使用しない。次のサンプル コードは、ActionMapper サンプルに定義されている DIACTION 型の配列を示す。CInputMapper は、ActionMapper サンプルが使用して定義するクラスであり、多くの標準アクション マッピング プロシージャを格納する。この例では、独自の AddAction 関数を使って、DIACTIONFORMAT 型に格納されている配列に新しい DIACTION 型を追加する。

Dim m_mapper As New CInputMapper

With m_mapper
.AddAction INPUT_LEFTRIGHT_AXIS, DIAXIS_SPACESIM_LATERAL, 0, "Turn"
.AddAction INPUT_UPDOWN_AXIS, DIAXIS_SPACESIM_MOVE, 0, "Move"
.AddAction INPUT_FIREWEAPONS, DIBUTTON_SPACESIM_FIRE, 0, "Shoot"
.AddAction INPUT_ENABLESHIELD, DIBUTTON_SPACESIM_GEAR, 0, "Shield"
.AddAction INPUT_DISPLAYGAMEMENU,DIBUTTON_SPACESIM_DISPLAY,0,"Display"
.AddAction INPUT_QUITGAME, DIBUTTON_SPACESIM_MENU, 0, "Quit Game"

' キーボード入力マッピング。
.AddAction INPUT_FORWARDTHRUST, DIKEYBOARD_UP, 0, "Forward thrust"
.AddAction INPUT_REVERSETHRUST, DIKEYBOARD_DOWN, 0, "Reverse thrust"
.AddAction INPUT_FIREWEAPONS, DIKEYBOARD_F, 0, "Fire weapons"
.AddAction INPUT_ENABLESHIELD, DIKEYBOARD_S, 0, "Enable shields"
.AddAction INPUT_DISPLAYGAMEMENU, DIKEYBOARD_D, 0, "Display game menu"
.AddAction INPUT_QUITGAME, DIKEYBOARD_ESCAPE, 0, "Quit game"
.AddAction INPUT_TURNRIGHT, DIKEYBOARD_RIGHT, 0, "Right Turn"
.AddAction INPUT_TURNLEFT, DIKEYBOARD_LEFT, 0, "Left Turn"

' マウス入力マッピング。
.AddAction INPUT_LEFTRIGHT_AXIS, DIMOUSE_XAXIS, 0, "Turn"
.AddAction INPUT_UPDOWN_AXIS, DIMOUSE_YAXIS, 0, "Move"
.AddAction INPUT_FIREWEAPONS, DIMOUSE_BUTTON0, 0, "Fire weapons"
.AddAction INPUT_ENABLESHIELD, DIMOUSE_BUTTON1, 0, "Enable shields"
End With

DIACTION 型の配列を格納する DIACTIONFORMAT 型を使って、そのアクションを使用するのに最適なデバイスを探し出す。これについては、「ステップ 3 : デバイスへのアクションのマッピング」で説明する。


ステップ 3 : デバイスへのアクションのマッピング

ActionMapper サンプルは、独自のクラス関数 CreateDevicesFromMap などを使って、前に定義したアクション マップと使用可能なデバイスを比較する。それにはまず、DIACTION 型の配列を格納する DIACTIONFORMAT 型のほかのメンバに値を割り当てる。サンプルで使用された値は、CreateDevicesFromMap メソッドにパラメータとして渡されている。わかりやすくするため、このサンプル コードではパラメータ名でなく実際の値を使用している。

    m_diaf.guidActionMap = "{20CAA014-60BC-4399-BDD3-84AD65A38A1C}"
    m_diaf.lGenre = DIVIRTUAL_SPACESIM
    m_diaf.lBufferSize = 16
    m_diaf.lAxisMax = 100
    m_diaf.lAxisMin = -100
    m_diaf.ActionMapName = "Semantic Mapper VB Sample"
    m_diaf.lActionCount = 18

guidActionMap 値はプログラムによって定義される。GUID の作成方法の詳細については、「GUID の使い方」を参照すること。

目的のマッピングが定義できたら、それを物理的デバイスに適用する。DirectInput8.GetDevicesBySemantics は、次のコードでこのプロセスを開始する。ここで m_DI は以前に定義された DirectInput8 オブジェクト、m_DIEnum は以前に定義された DirectInputEnumDevices8 オブジェクト、m_strUserName は以前に定義されたユーザーのわかりやすい識別子を含む文字列である。

Set m_DIEnum = m_DI.GetDevicesBySemantics(m_strUserName, m_diaf, 0)

フラグを使って列挙対象をさらに限定することもできるが、この例ではフラグは設定されていない。

列挙の結果が個々に調べられ、見つかった各キーボード、マウス、ジョイスティックに対してデバイスが作成される。次のサンプル コードで、devinst は以前に定義された DirectInputDeviceInstance8 オブジェクト、m_Devices は以前に定義された DirectInputDevice8 オブジェクトの配列、m_DeviceTypes は以前に定義された Long 値の配列である。

    For i = 1 To m_DIEnum.GetCount

        Set devinst = m_DIEnum.GetItem(i)
        Set m_Devices(i) = m_DI.CreateDevice(devinst.GetGuidInstance)
        m_DeviceTypes(i) = devinst.GetDevType
        Set devinst = Nothing

ループは、現在調べている列挙デバイスがマウスかどうかをチェックすることによって、実行を続ける。マウスの場合は、AXISMODE プロパティが相対に設定される。このループ内にほかのプロパティを設定することもできるが、ActionMapper サンプルでは、これだけが実行される。

        If m_DeviceTypes(i) = DI8DEVTYPE_MOUSE Then
            Dim dipl As DIPROPLONG
            dipl.lHow = DIPH_DEVICE
            dipl.lData = DIPROPAXISMODE_REL
            m_Devices(i).SetProperty "DIPROP_AXISMODE", dipl
        End If

DirectInputDevice8.BuildActionMap は、DIACTIONFORMAT 型に指定されているコントロールの割り当て一覧を取得し、m_strUserName パラメータに指定されているユーザーに対して列挙されているデバイスの特定のデバイス オブジェクトにそれをマッッピングしようとする。マッピングの結果は、同じ構造体に返される。渡すたびに、現在調べられている列挙デバイスの性質に応じて、異なるコントロールにマッピングされる。たとえばキーボードは、特定のキーへのマッピングを指定するコントロールをマッピングするが、ボタン、スライダ、または軸を指定するコントロールについてはマッピングしない。次にジョイスティックが列挙された場合、BuildActionMap はキーボードのキーにマッピングされたコントロールは無視するが、ボタン、スライダ、軸はジョイスティックのデバイス オブジェクトへのマッピングを試みる。

        m_Devices(i).BuildActionMap m_diaf, m_strUserName, 0

この例でもフラグは使用されていない。

このデフォルト マッピングの結果を調べ、操作することができる。これは、「ステップ 4 : アクション マップの構成と適用」で行う。


ステップ 4 : アクション マップの構成と適用

DIACTIONFORMAT 型にマッピングが返されたら、操作してから DirectInputDevice8.SetActionMap によって適用する。

この時点で、DIACTIONFORMAT 型に格納されている各 DIACTION 型の lHow メンバを調べ、マッピングが成功したか、また各アクションがマッピングされたデバイス オブジェクトの選択基準は何であったかを判断することができる。たとえば、マッピングがハードウェア メーカーによる指定か、またはユーザーからの要求かを判断できる。

実際のマッピングそのものを変更するには、デフォルト マッピングに返された適切な DIACTION 構造体の lSemantic メンバを編集する。しかし、このような変更は勧められない。

アクション マップの構成が終わったら、それをデバイスに適用し、物理的コントロールをゲーム アクションにバインドする必要がある。これを行うには、次に示すように DirectInputDevice8.SetActionMap メソッドを呼び出す。

        m_Devices(i).SetActionMap m_diaf, m_strUserName, 0

このときもパラメータは、DIACTIONFORMAT 型、ユーザー名、フラグなしで構成される。

作成されたアクション マップはユーザーに対して表示され、簡単に変更することができる。これについては、「ステップ 5 : アクション マップの表示」で説明する。


ステップ 5 : アクション マップの表示

アクション マッピングには、開発者が特定のコントローラ ハードウェアに依存せずにゲーム アクションを定義できるという利点のほか、ユーザーによる再構成を容易にするユーザー インターフェイス (UI) が提供される利点もある。

UI は、テキストのみとグラフィックの 2 つの形式で表示できる。また、これら 2 つのオプションを表示専用モードまたは編集モードで表示できる。

UI を表示するには、事前にいくつかの設定が必要となる。DICONFIGUREDEVICESPARAMS 型を使って、プロパティ シートの情報を保持する。DICONFIGUREDEVICESPARAMS は DIACTIONFORMAT 型の配列を格納する。この配列は、定義されたマッピング、それらのアクション マップに一致するユーザー名の配列、両方の配列のカウントに使用される。この例では、1 つのマッピングと一人のユーザーが定義されている。次のサンプル コードは DICONFIGUREDEVICESPARAMS 型の初期化を示している。

Dim m_cdParams As DICONFIGUREDEVICESPARAMS

    m_cdParams.ActionFormats(0) = m_diaf
    m_cdParams.FormatCount = 1
    m_cdParams.UserNames(0) = m_strUserName
    m_cdParams.UserCount = 1

構造体が初期化されたら、DirectInput8.ConfigureDevices を呼び出して、UI を表示する。これを、次のサンプル コードに示す。

    m_DI.ConfigureDevices 0, m_cdParams, DICD_EDIT

ConfigureDevices に渡されるサンプルはすべて DICONFIGUREDEVICESPARAMS 型と、UI でユーザー構成が可能であることを示すフラグである。これについては、「ステップ 6 : アクション マップのユーザー構成」で説明する。


ステップ 6 : アクション マップのユーザー構成

この時点で、ユーザー構成インターフェイスが表示される。デバイス メーカーがグラフィックを提供している場合はデバイスのイメージが表示され、そのイメージのラベルには各デバイス オブジェクトに割り当てられたアクションが示されている。グラフィックがない場合、使用できるデバイス オブジェクトが関連付けられているアクションと共に、簡単なテキストによる一覧が表示される。次にグラフィックの例を示す。

ここでユーザーは、自分の判断でコントローラをアクションに再割り当てできる。変更結果は、DIACTIONFORMAT 型に反映される。ユーザー インターフェイスを終了すると、新しいアクション マップが DirectInputDevice8.SetActionMap に送られ、実装される。

アクション マップのコントロールに関連付けられたデータの使い方については、「ステップ 7 : アクション マッピングされたデータの取得」で説明する。


ステップ 7 : アクション マッピングされたデータの取得

アクション マッピングはバッファリング データを念頭に置いて設計されており、大部分はバッファリング データで使用される。アクション マッピングされたデバイスからのデータ取得とマッピングされていないデバイスからのデータ取得では、データを取得する場所のみが異なっている。アクション マッピングがない場合は、DIDEVICEOBJECTDATA 型の lOfs メンバを調べて、変更の報告があるデバイス オブジェクトを判断する。しかしアクション マッピングでは、lUserData メンバを調べる。データは通常どおり lData メンバで見つかる。


DirectInput Visual Basic サンプル

以下のサンプル プログラムには、Microsoft® DirectInput® の使い方と機能が示されている。

  • ActionMapper サンプル
  • ForceFeedback サンプル
  • Joystick サンプル
  • Keyboard サンプル
  • ScrawlB サンプル


ActionMapper サンプル

説明

ActionMapper サンプル プログラムは、アクション マッピングされたデータの取得方法を示している。また、ユーザー インターフェイスによるキーボード、マウス、その他コントローラのアクション マッピングの再構成も可能である。

パス

ソース ファイル : (SDK ルート)\Samples\Multimedia\VBSamples\DirectInput\ActionMapper

実行可能ファイル : (SDK ルート)\Samples\Multimedia\VBSamples\DirectInput\Bin\VB_ActionMapper.exe

ユーザーズ ガイド

初期画面では、システムに接続されているマウス、キーボード、その他コントローラからの軸移動、ボタンやキーの押し下げをテキストでフィードバックすることができる。排他 | フォアグラウンド協調レベルが使用されているため、マウス カーソルは隠されている。

D キーを押すと、マウス、キーボード、その他使用しているコントローラ デバイスのタブがある構成ユーザー インターフェイスが表示される。コントローラにグラフィックがある場合はそのグラフィックが表示され、各コントロールに関連付けられているアクションがコールアウトで示される。コールアウトのラベルをダブルクリックすると、そのコントロールに適用できるアクションのメニューがアクティブになる。マッピングの設定を変更して初期画面に戻るには、[OK] をクリックする。

プログラムを終了するには、初期画面で Esc キーを押す。

プログラミング上の注意

ActionMap.cls を修正する必要がある。このサンプルの用途として、プログラムは入力デバイスを照会し、入力ソースは区別しない。しかし普通は、クラスを修正して指定した入力のみに応答するようにするか、または入力デバイスを異なるプレーヤーや用途に割り当てて区別する。

このサンプルは、DirectX SDK のほかのサンプルと共有する共通の DirectX コードを使用する。共通のクラスおよびモジュールは、すべて次のディレクトリに入っている。

(SDK ルート)\Samples\Multimedia\VBSamples\Common


ForceFeedback サンプル

説明

ForceFeedback サンプルは、エフェクトの生成、パラメータの設定、およびエフェクトの再生を行うことができる簡単なフォース フィードバック エディタである。

パス

ソース ファイル : (SDK ルート)\Samples\Multimedia\VBSamples\DirectInput\Feedback

実行可能ファイル :(SDK ルート)\Samples\Multimedia\VBSamples\DirectInput\Bin\VB_ForceFeedback.exe

ユーザーズ ガイド

一覧からエフェクト タイプを選択し、パラメータを変更する。ジョイスティックの主ボタンを押すと、エフェクトが再生される。

プログラミング上の注意

ForceFeedback サンプルでは、自動センタリング プロパティをオフにする方法、およびエフェクトを生成して変更する方法を示す。エフェクト パラメータの変更は、直ちに適用される。


Joystick サンプル

説明

Joystick サンプル プログラムでは、ジョイスティックを列挙し、ジョイスティックのプロパティを設定し、直接データを取得する方法を示す。

パス

ソース ファイル : (SDK ルート)\Samples\Multimedia\VBSamples\DirectInput\Joystick

実行可能ファイル :(SDK ルート)\Samples\Multimedia\VBSamples\DirectInput\Bin\VB_Joystick.exe

ユーザーズ ガイド

一覧からジョイスティックを選択する。軸およびボタンから取得されたデータが表示される。スティックの移動やねじり、スロットル ホイールの回転、ボタンの押し下げをいろいろ組み合わせて実行し、表示データの変化を観察する。

プログラミング上の注意

選択肢が DirectInputEnumDevices8 コレクションから容易に取得できるように、リスト ボックスはソートされない。


Keyboard サンプル

説明

Keyboard サンプル プログラムでは、キーボード デバイスを作成して直接データを取得する方法を示す。

パス

ソース ファイル : (SDK ルート)\Samples\Multimedia\VBSamples\Dinput\Src\Keyboard

実行可能ファイル :(SDK ルート)\Samples\Multimedia\VBSamples\Dinput\Bin\Keyboard.exe

ユーザーズ ガイド

アプリケーションにフォーカスがあるときに 1 つまたは複数のキーを押すと、リスト ボックスに (CONST_DIKEYFLAGS から) キー名が表示される。

プログラミング上の注意

バックグラウンド協調レベルを使用するので、アプリケーションに入力フォーカスがなくても、キーは読み取られる。


ScrawlB サンプル

説明

ScrawlB サンプル プログラムでは、Microsoft® DirectInput® を使って簡単な描画プログラムを作成する方法を示す。ここでは、排他モードでのマウスの使い方、マウス イベントのイベント通知の使い方、バッファリング データの取得方法と解釈方法、コールバック関数を使ってマウスの移動イベントを取得する方法を説明する。

パス

ソース ファイル : (SDK ルート)\Samples\Multimedia\VBSamples\DirectInput\Scrawl

実行可能ファイル :(SDK ルート)\Samples\Multimedia\VBSamples\DirectInput\Bin\VB_Scrawlb.exe

ユーザーズ ガイド

左ボタンを押しながらマウスをドラッグすると、描画できる。右ボタンをクリックすると、ショートカット メニューが表示される。[Release Mouse] を選択する (または Alt キーを押して離す) と、システム カーソルが解放されるので、ウィンドウを移動したり、ウィンドウのサイズを変更したり、別のアプリケーションをクリックしたりできる。描画を再開するには、クライアント ウィンドウをもう一度クリックする。

プログラミング上の注意

アプリケーションは 表示ウィンドウをサブクラス化して、WM_ENTERMENULOOP メッセージをキャプチャする。ユーザーが Alt キーを押しながら Space キーを押してシステム メニューを開いたかどうかを調べるには、これが最適な方法である。これがわかれば、ScrawlB は SetWindowLong を呼び出してマウスを解放できる。ただし、サブクラス化すると、デバッグ時に問題が生じることがある。Visual Basic 環境でサンプルを実行したとき、このような行をコメント アウトできなかった場合は、予期できない動作が発生する。

frmCanvas モジュールは、入力イベントを処理するために DirectXEvent8 を実装する。また、このフォームでは、Microsoft DirectInput® がマウスに対するアクセス権を持たないときに Microsoft Windows® マウス イベントを取得するために、Microsoft® Visual Basic® の MouseMove イベントを使用する。このイベントがトリガされると、アプリケーションはカーソルがクライアント ウィンドウに戻ったことを認識するので、マウスを再取得することができる。


DirectInput Visual Basic リファレンス

Microsoft® DirectInput® の Microsoft Visual Basic® API のリファレンス情報は、以下のカテゴリに分類される。

  • クラス
  • 型
  • 列挙
  • キーボード キー
  • アクション マッピング定数
  • エラー コード


クラス

ここでは、以下の Microsoft® DirectInput® クラスのメソッドに関するリファレンスを提供する。

  • DirectInput8
  • DirectInputDevice8
  • DirectInputDeviceInstance8
  • DirectInputDeviceObjectInstance
  • DirectInputEffect
  • DirectInputEnumDeviceObjects
  • DirectInputEnumDevices8
  • DirectInputEnumEffects


DirectInput8

DirectInput8 クラスは、Microsoft® DirectInput® システムを表す。アプリケーションは、このクラスの単一のオブジェクトを持ち、Microsoft Windows® コントロール パネルのインスタンスの起動のほか、利用可能なデバイスの列挙、デバイスの作成、およびデバイスの状態の取得を行うのに使用される。

DirectInput8 オブジェクトを取得するには、DirectX8.DirectInputCreate メソッドを使用する。

DirectInput8 クラスには、次のメソッドがある。

アクション マッピング | ConfigureDevices
 | GetDevicesBySemantics
デバイス管理 | CreateDevice
 | GetDeviceStatus
 | GetDIDevices
その他 | RunControlPanel


DirectInput8.ConfigureDevices

接続された入力デバイスのプロパティ ページを表示する。ユーザーはこれを使って、アクションをデバイス コントロールにマップできる。

object.ConfigureDevices( _
  hEvent As Long, _
  CDParams As DICONFIGUREDEVICESPARAMS, _
  flags As Long)

指定項目

object
DirectInput8 オブジェクトを指定する。
hEvent
プロパティ シートの表示に変更があるたびに設定されるイベントのハンドル。ゼロ、または DirectX8.CreateEvent が返す値を使用できる。
CDParams
アクション マッピング用パラメータを格納する DICONFIGUREDEVICESPARAMS 型。
flags
コントロール パネルの起動モードを指定する値。次の CONST_DICDFLAGS 列挙のいずれか 1 つの値でなければならない。
DICD_DEFAULT
プロパティ シートを表示専用モードで開く。
DICD_EDIT
プロパティ シートを編集モードで開く。このモードでは、ユーザーがアクションとコントロールのマッピングを変更できる。呼び出しが戻ると、アプリケーションは現在のデバイスがもう有効ではないと仮定して、デバイス インターフェイスを解放し、DirectInput8.GetDevicesBySemantics を呼び出してそのインターフェイスを初期化する。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかのエラー コードが設定される。

DIERR_INVALIDPARAM
DIERR_OUTOFMEMORY

注意

ハードウェア ベンダーは、デバイスのビットマップおよびその他の表示情報を提供する。

このメソッドを呼び出す前に、DIACTION 型の ActionName メンバ内の値を変更することで、アプリケーションは各アクションに関連付けられたテキスト ラベルを変更できる。

構成は、ゲームごと、デバイスごと、ユーザーごとに格納される。この情報は、DirectInputDevice8.BuildActionMap メソッドで取得できる。

デフォルトでは、以下のピクセル フォーマットに対してアクセラレーションがサポートされている。

A1R5G5B5
16 ビットのピクセル フォーマットで、各色に 5 ビットが、アルファ (透過型テクセル) に 1 ビットが、それぞれ確保されている。
A8R8G8B8
アルファ付きの 32 ビット ARGB ピクセル フォーマット。
R9G8B8
24 ビット RGB ピクセル フォーマット。
X1R5G5B5
16 ビットのピクセル フォーマットで、そのうち 5 ビットは各色のために確保されている。
X8R8G8B8
32 ビットの RGB ピクセル フォーマットで、そのうち 8 ビットは各色のために確保されている。

上記以外のフォーマットではカラー変換が施されてしまい、フレーム レートが劇的に低下する。

注 : Windows キーは、アプリケーションの協調レベルで排他協調レベルを通して受動的に、または DISCL_NOWINKEY フラグを使って能動的に無効にする場合でも、デフォルトのアクション マッピング UI が表示されている間はアクティブになる。


DirectInput8.CreateDevice

指定された GUID に基づいてデバイスのインスタンスを作成し、初期化する。

object.CreateDevice(guid As String) As DirectInputDevice8

指定項目

object
DirectInput8 オブジェクトを指定する。
guid
目的の入力デバイスを表すインスタンス GUID。この GUID は、DirectInputEnumDevices8.GetItem メソッドが返す DirectInputDeviceInstance8 オブジェクトから返される。次の文字列のいずれかを使用することもできる。
GUID_SysKeyboard
デフォルトのシステム キーボード。
GUID_SysMouse
デフォルトのシステム マウス。

戻り値

DirectInputDevice8 オブジェクトが返される。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかのエラー コードが設定される。

DIERR_DEVICENOTREG
DIERR_INVALIDPARAM
DIERR_NOINTERFACE
DIERR_OUTOFMEMORY

参照

DirectInput8、GUID の使い方


DirectInput8.GetDevicesBySemantics

アプリケーション指定のアクション マップに最も一致するデバイスを列挙する。

object.GetDevicesBySemantics( _
  str1 As String, _
  format As DIACTIONFORMAT, _
  flags As Long _
) As DirectInputEnumDevices8

指定項目

object
DirectInput8 オブジェクトを指定する。
str1
現在のユーザーを識別する文字列。システムにログオンしたユーザーを指定する場合は vbNullString。ユーザー名はデバイスの列挙時に考慮される。ユーザー マッピングのないデバイスよりも、ユーザー マッピングを持つデバイスが優先される。デフォルトでは、ほかのユーザーが使用中のデバイスは、このユーザー用には列挙されない。
format
列挙する適切なデバイスのアクション マップを指定する DIACTIONFORMAT 型。
flags
列挙の範囲を指定するフラグ値。CONST_DIEDBSFLFLAGS 列挙のいずれか 1 つの値を使用できる。

戻り値

列挙されたデバイスのコレクションを表す DirectInputEnumDevices8 オブジェクトが返される。

エラー コード

失敗した場合はエラーが発生し、Err.Number が設定される。

注意

キーボードとマウスは最後に列挙される。

参照

「アクション マッピング」


DirectInput8.GetDeviceStatus

デバイスがシステムにアタッチ状態にあるかどうかを判定する。

object.GetDeviceStatus(guid As String) As Boolean

指定項目

object
DirectInput8 オブジェクトを指定する。
guid
目的の入力デバイスを表すインスタンス GUID。GUID は、DirectInputEnumDevices8.GetItem メソッドが返すオブジェクトの DirectInputDeviceInstance8.GetGuidInstance メソッドを使って取得される。次の文字列のいずれかを使用することもできる。
GUID_SysKeyboard
デフォルトのシステム キーボード。
GUID_SysMouse
デフォルトのシステム マウス。

戻り値

デバイスがアタッチ状態にある場合に TRUE が返され、それ以外の場合は FALSE が返される。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかのエラー コードが設定される。

DIERR_GENERIC
DIERR_INVALIDPARAM

参照

DirectInput8、GUID の使い方


DirectInput8.GetDIDevices

利用可能なデバイスを列挙する。

object.GetDIDevices( _
  deviceType As CONST_DI8DEVICETYPE, _
  flags As CONST_DIENUMDEVICESFLAGS) _
  As DirectInputEnumDevices8

指定項目

object
DirectInput8 オブジェクトを指定する。
deviceType
列挙するデバイスのタイプを指定する値。このパラメータがゼロなら、すべてのタイプが列挙される。それ以外は、デバイスのクラスまたはタイプを表す CONST_DI8DEVICETYPE 列挙の定数の 1 つである。
flags
列挙の範囲を指定するフラグ値。このパラメータには、次の CONST_DIENUMDEVICESFLAGS 列挙の 1 つ以上の定数が含まれる。

戻り値

DirectInputEnumDevices8 オブジェクトが返される。

エラー コード

失敗した場合はエラーが発生し、Err.Number が設定される。

注意

すべてのインストール済みデバイスは、たとえそれが現存していなくても列挙可能である。たとえば、ジョイスティックは、システムにインストールするが、当面コンピュータに接続しないでおくこともできる。

単一のハードウェアが、複数の Microsoft® DirectInput® デバイス タイプとして機能することができる場合は、サポートする各デバイス タイプごとに返される。たとえば、組み込みマウス付きのキーボードは、1 つのキーボードとして、かつ、1 つのマウスとして列挙される。ただし、製品 GUID は各デバイスに対して同じである。

参照

DirectInput8


DirectInput8.RunControlPanel

ユーザーが新しい入力デバイスをインストールしたり、構成を変更したりできるように、Microsoft® Windows® コントロール パネルを実行する。

object.RunControlPanel(hwndOwner As Long)

指定項目

object
DirectInput8 オブジェクトを指定する。
hwndOwner
これ以降のユーザー インターフェイスの親ウィンドウとして使用するウィンドウのハンドル。このパラメータがゼロなら、親ウィンドウは使用されない。

エラー コード

失敗した場合はエラーが発生し、Err.Number が設定される。

参照

DirectInput8、DirectInputDevice8.RunControlPanel


DirectInputDevice8

アプリケーションは、DirectInputDevice8 クラスのメソッドを使用して、Microsoft® DirectInput® デバイスのアクセス権の取得と解放、デバイス プロパティと情報の管理、動作の設定、初期化の実行、およびデバイスのプロパティ シートの起動を行う。

DirectInputDevice8 オブジェクトを取得するには、DirectInput8.CreateDevice メソッドを使用する。

DirectInputDevice8 クラスのメソッドは、以下のグループにまとめることができる。

アクセス | Acquire
 | SetCooperativeLevel
 | Unacquire
アクション マッピング | BuildActionMap
 | GetImageInfo
 | GetImageInfoCount
 | SetActionMap
データ取得 | GetDeviceData
 | GetDeviceState
 | GetDeviceStateJoystick
 | GetDeviceStateJoystick2
 | GetDeviceStateKeyboard
 | GetDeviceStateMouse
 | GetDeviceStateMouse2
 | Poll
 | SetEventNotification
フォース フィードバック | CreateCustomEffect
 | CreateEffect
 | CreateEffectFromFile
 | GetEffectsEnum
 | GetForceFeedbackState
 | SendForceFeedbackCommand
 | WriteEffectToFile
オブジェクト | GetDeviceObjectsEnum
 | GetObjectInfo
プロパティ | GetCapabilities
 | GetDeviceInfo
 | GetProperty
 | SetCommonDataFormat
 | SetDataFormat
 | SetProperty
その他 | RunControlPanel
 | SendDeviceData


DirectInputDevice8.Acquire

入力デバイスへのアクセス権を取得する。

object.Acquire()

指定項目

object
DirectInputDevice8 オブジェクトを指定する。

エラー コード

失敗した場合は、エラーが発生し、Err.Number に次のいずれかの戻り値が設定される。

DIERR_INVALIDPARAM
DIERR_OTHERAPPHASPRIO

注意

デバイスを取得する前に、DirectInputDevice8.SetDataFormat メソッドまたは DirectInputDevice8.SetCommonDataFormat メソッドを使ってデータ形式を設定しなければならない。

デバイスから入力データを取得する前に、デバイスを取得しなければならない。

参照

DirectInputDevice8.Unacquire


DirectInputDevice8.BuildActionMap

デバイスのアクション マップを構築し、それに関する情報を取得する。

object.BuildActionMap( _
  format As DIACTIONFORMAT, _
  username As String, _
  flags As Long)

指定項目

object
DirectInputDevice8 オブジェクトを指定する。
format
アクション マップのプロパティを受け取る DIACTIONFORMAT 型。
username
どのユーザーのマッピングを要求しているかを指定する文字列。空の文字列の場合、現在のユーザーが想定される。
flags
マッピングを制御するフラグ。CONST_DIDBAMFLAGS 列挙の定数のいずれかを取ることができる。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかのエラー コードが設定される。

DIERR_INVALIDPARAM
DIERR_MAPFILEFAIL

注意

DIERR_INVALIDPARAM が発生する場合、マッピングの 1 つ以上が無効である。DIACTION 型の lHow メンバには DIAH_ERROR が設定される。アプリケーションは、アクション マップの全体でエラーの検出と修正を補間することができる。

参照

DirectInputDevice8.SetActionMap、DirectInputDevice8.SetDataFormat


DirectInputDevice8.CreateCustomEffect

固定的な継続時間を持つ一連のコンスタント フォースで構成されるフォース フィードバック エフェクトを生成する。

object.CreateCustomEffect(effectinfo As DIEFFECT, _
    channels As Long, samplePeriod As Long, _
    nSamples As Long, sampledata() As Long) _
    As DirectInputEffect

指定項目

object
DirectInputDevice8 オブジェクトを指定する。
effectinfo
エフェクトの一般的なパラメータを格納する DIEFFECT 型。
channels
このフォースによって影響されるチャネル (軸) の数。1 または 2 でなければならない。

チャネルが 1 つしか存在しない場合、エフェクトは、DIEFFECT 型の x メンバが指定する方向に回転する。カスタム エフェクトの回転をサポートしていないデバイスもある。

複数のチャネルが存在する場合、第 1 チャネルは x 軸に適用され、第 2 チャネルは y 軸に適用される。回転は許可されない。

samplePeriod
マイクロ秒単位のサンプリング間隔。「注意」を参照すること。
nSamples
sampledata 配列中の要素の数。
sampledata
マグニチュードの配列。channels が 2 以上であれば、各値は順番に割り当てられる。たとえば、channels が 2 の場合、配列の第 1 要素は x 軸、第 2 要素は y 軸、第 3 要素は x 軸に割り当てられる。チャネルがこれより多い場合も同様である。

注意

理論的には、samplePeriod は sampledata に含まれる有効な各マグニチュードの時間の長さである。他方、DIEFFECT.lSamplePeriod は、データのサンプリング間隔 (およびマグニチュードの変化間隔の最小時間) の長さである。配列内の各要素は、配列全体を補間処理する際に一度だけサンプリングする必要があるが、ドライバによってはどのような場合にも samplePeriod を無視することがあるので、lSamplePeriod と samplePeriod の値を同じにすることが望ましい。

参照

「カスタム フォース」


DirectInputDevice8.CreateEffect

フォース フィードバック エフェクトを作成する。デバイスが現在排他協調レベルで取得されている場合、エフェクトのダウンロードも行われる。

object.CreateEffect(effectGuid As String, _
  effectinfo As DIEFFECT) As DirectInputEffect

指定項目

object
DirectInputDevice8 オブジェクトを指定する。
effectGuid
ハードウェア ドライバにより認識されるエフェクトの GUID の文字列表現。標準のエフェクトを表す次のエイリアスのいずれかを使用できる。

GUID_ConstantForce
GUID_RampForce
GUID_Square
GUID_Sine
GUID_Triangle
GUID_SawtoothUp
GUID_SawtoothDown
GUID_Spring
GUID_Damper
GUID_Inertia
GUID_Friction

effectinfo
作成されたエフェクトに対するパラメータを格納する DIEFFECT 型。

戻り値

DirectInputEffect オブジェクトを返す。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかのエラー コードが設定される。

DIERR_DEVICEFULL
DIERR_DEVICENOTREG
DIERR_INVALIDPARAM
DIERR_NOTINITIALIZED

注意

エラーが発生しない場合、エフェクトは作成済みで、エフェクトのパラメータは更新済みであるが、エフェクトは必ずしもダウンロードされていない。エフェクトをダウンロードするには、デバイスを排他モードで取得しなければならない。

参照

DirectInputDevice8.CreateEffectFromFile

DirectInputEffect.Download

DirectInputEffect.Start


DirectInputDevice8.CreateEffectFromFile

フォース フィードバック エフェクトを作成し、そのパラメータをファイルに保存する。デバイスが現在排他協調レベルで取得されている場合、エフェクトのダウンロードも行われる。

object.CreateEffectFromFile( _
  filename As String, _
  flags As Long, _
  effectName As String _
) As DirectInputEffect

指定項目

object
DirectInputDevice8 オブジェクトを指定する。
filename
ファイル名を指定する文字列。
flags
エフェクトの作成方法を指定するフラグ。CONST_DIFEFFLAGS 列挙のいずれか 1 つの値を使用できる。
effectName
作成者が設定するエフェクトの登録名。

戻り値

DirectInputEffect オブジェクトを返す。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかのエラー コードが設定される。

DIERR_DEVICEFULL
DIERR_DEVICENOTREG
DIERR_INVALIDPARAM
DIERR_NOTINITIALIZED

注意

エラーが発生しない場合、エフェクトは作成され、エフェクトのパラメータはアップデートされた、しかしエフェクトは必ずしもダウンロードされてはいないことを意味する。エフェクトをダウンロードするには、デバイスを排他モードで取得しなければならない。

エフェクト ファイルは、Microsoft® DirectInput® SDK に付属する Force Editor アプリケーションで使用できる形式でなければならない。

参照

DirectInputEffect.Download、DirectInputDevice8.WriteEffectToFile


DirectInputDevice8.GetCapabilities

デバイスの能力を取得する。

object.GetCapabilities(caps As DIDEVCAPS)

指定項目

object
DirectInputDevice8 オブジェクトを指定する。
caps
デバイスの能力を格納する DIDEVCAPS 型。

エラー コード

失敗した場合はエラーが発生し、Err.Number が設定される。


DirectInputDevice8.GetDeviceData

デバイスからバッファリング データを取得する。

object.GetDeviceData( _
  deviceObjectDataArray() As DIDEVICEOBJECTDATA, _
  flags As CONST_DIDGDDFLAGS) As Long

指定項目

object
DirectInputDevice8 オブジェクトを指定する。
deviceObjectDataArray()
バッファリング データを受け取るための DIDEVICEOBJECTDATA 型の配列。
flags
データの取得方法を制御するフラグ。この値は、ゼロか、CONST_DIDGDDFLAGS 列挙の定数のいずれかを取ることができる。

戻り値

deviceObjectDataArray に実際に返されたバッファリング データ要素数が返される。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかのエラー コードが設定される。

DIERR_INPUTLOST
DIERR_INVALIDPARAM
DIERR_NOTACQUIRED
DIERR_NOTBUFFERED

注意

デバイスを取得する前に、DirectInputDevice8.SetDataFormat メソッドでデータ形式を設定し、DirectInputDevice8.SetProperty メソッドでバッファ サイズを設定し、DirectInputDevice8.Acquire メソッドでデバイスを取得しておかなければならない。

このメソッドを使って、SetProperty で作成したバッファから 1 つ以上の入力イベントを取得することができる。一度の呼び出しで、待機中のすべてのイベントを取得する必要はない。たとえば、単一の要素で構成される deviceObjectDataArray() に渡し、すべてのデータが返されるまで GetDeviceData をループ処理することができる。

バッファがオーバーフローすると、待機中のすべてのデータは失われ、DI_BUFFEROVERFLOW エラーが発生する。

参照

DirectInputDevice8.Poll、ポーリングとイベント通知


DirectInputDevice8.GetDeviceInfo

デバイスの識別情報を取得する。

object.GetDeviceInfo() As DirectInputDeviceInstance8

指定項目

object
DirectInputDevice8 オブジェクトを指定する。

戻り値

DirectInputDeviceInstance8 オブジェクトが返される。

エラー コード

失敗した場合はエラーが発生し、Err.Number が設定される。


DirectInputDevice8.GetDeviceObjectsEnum

デバイス上で使用可能な入出力オブジェクトを列挙する。

object.GetDeviceObjectsEnum( _
  flags As CONST_DIDFTFLAGS) _
  As DirectInputEnumDeviceObjects

指定項目

object
DirectInputDevice8 オブジェクトを指定する。
flags
列挙するオブジェクトのタイプを指定するフラグ。CONST_DIDFTFLAGS 列挙の 1 つ以上のメンバを指定できる。

戻り値

成功すれば、列挙されたデバイスのコレクションを表す DirectInputEnumDeviceObjects が返される。

エラー コード

失敗した場合はエラーが発生し、Err.Number が設定される。

注意

DIDFT_FFACTUATOR および DIDFT_FFEFFECTTRIGGER のフラグを指定すると、列挙対象は、この 2 つのフラグで定義されているすべての基準を満たすオブジェクトに限定される。ほかのすべてのフラグの場合は、このカテゴリに指定したフラグで定義されている基準を満たすオブジェクトが列挙される。たとえば、(DIDFT_FFACTUATOR Or DIDFT_FFEFFECTTRIGGER) は、列挙対象をフォース フィードバック トリガ オブジェクトに限定する。これに対して、(DIDFT_FFEFFECTRIGGER Or DIDFT_TGLBUTTON Or DIDFT_PSHBUTTON) は、エフェクト トリガとして利用できる任意のボタンが列挙される。

アプリケーションは、特定のキーボードのキーやインジケータ ランプが存在するかどうかの確認を列挙に依存するべきではない。これらのオブジェクトは、存在しないにもかかわらず列挙される可能性がある。利用可能なオブジェクトの基本セットはデバイス サブタイプから決定できるものの、メニュー キーなどの追加オブジェクトが利用できるかどうかを確実に判断できる方法はない。


DirectInputDevice8.GetDeviceState

標準のキーボード、マウス、またはジョイスティック以外のデバイスの直接データを取得する。

object.GetDeviceState(cb As Long, state As Any)

指定項目

object
DirectInputDevice8 オブジェクトを指定する。
cb
先頭要素が state として渡される配列のサイズ。
state
デバイスの状態情報を受け取る配列の先頭要素。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかのエラー コードが設定される。

DIERR_INPUTLOST
DIERR_INVALIDPARAM
DIERR_NOTACQUIRED
E_PENDING

注意

デバイス データを取得する前に、DirectInputDevice8.SetCooperativeLevel メソッドで協調レベルを設定した後、DirectInputDevice8.SetDataFormat メソッドでデータ形式を設定し、DirectInputDevice8.Acquire メソッドでデバイスを取得しておかなければならない。

参照

DirectInputDevice8.GetDeviceStateJoystick、DirectInputDevice8.GetDeviceStateJoystick2、DirectInputDevice8.GetDeviceStateKeyboard、DirectInputDevice8.GetDeviceStateMouse、DirectInputDevice8.SetDataFormat、「バッファリング データと直接データ」


DirectInputDevice8.GetDeviceStateJoystick

ジョイスティック デバイスから直接データを取得する。

object.GetDeviceStateJoystick(state As DIJOYSTATE)

指定項目

object
DirectInputDevice8 オブジェクトを指定する。
state
デバイスの現在の状態を受け取る DIJOYSTATE 型。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかのエラー コードが設定される。

DIERR_INPUTLOST
DIERR_INVALIDPARAM
DIERR_NOTACQUIRED
E_PENDING

注意

デバイス データを取得する前に、DirectInputDevice8.SetCooperativeLevel メソッドを使用して協調レベルを設定してから、DirectInputDevice8.SetCommonDataFormat を使用してデータ形式を設定し、DirectInputDevice8.Acquire メソッドを使用してデバイスを取得する必要がある。

参照

DirectInputDevice8.Poll、ポーリングとイベント通知


DirectInputDevice8.GetDeviceStateJoystick2

拡張機能の付いたジョイスティック デバイスから直接データを取得する。

object.GetDeviceStateJoystick2(state As DIJOYSTATE2)

指定項目

object
DirectInputDevice8 オブジェクトを指定する。
state
デバイスの現在の状態を受け取る DIJOYSTATE2 型。データ形式は、先に DirectInputDevice8.SetDataFormat メソッドを呼び出すことで設定される。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかのエラー コードが設定される。

DIERR_INPUTLOST
DIERR_INVALIDPARAM
DIERR_NOTACQUIRED
E_PENDING

注意

デバイス データを取得する前に、DirectInputDevice8.SetCooperativeLevel メソッドを使用して協調レベルを設定してから、DirectInputDevice8.SetCommonDataFormat を使用してデータ形式を設定し、DirectInputDevice8.Acquire メソッドを使用してデバイスを取得する必要がある。

参照

DirectInputDevice8.Poll、ポーリングとイベント通知


DirectInputDevice8.GetDeviceStateKeyboard

キーボード デバイスから直接データを取得する。

object.GetDeviceStateKeyboard(state As DIKEYBOARDSTATE)

指定項目

object
DirectInputDevice8 オブジェクトを指定する。
state
デバイスの現在の状態を受け取る DIKEYBOARDSTATE 型。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかのエラー コードが設定される。

DIERR_INPUTLOST
DIERR_INVALIDPARAM
DIERR_NOTACQUIRED
E_PENDING

注意

デバイス データを取得する前に、DirectInputDevice8.SetCooperativeLevel メソッドを使用して協調レベルを設定してから、DirectInputDevice8.SetCommonDataFormat を使用してデータ形式を設定し、DirectInputDevice8.Acquire メソッドを使用してデバイスを取得する必要がある。

参照

DirectInputDevice8.Poll、ポーリングとイベント通知


DirectInputDevice8.GetDeviceStateMouse

4 つまでのボタンを持つマウス デバイスから直接データを取得する。

object.GetDeviceStateMouse(state As DIMOUSESTATE)

指定項目

object
DirectInputDevice8 オブジェクトを指定する。
state
デバイスの状態を受け取る DIMOUSESTATE 型。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかのエラー コードが設定される。

DIERR_INPUTLOST
DIERR_INVALIDPARAM
DIERR_NOTACQUIRED
E_PENDING

注意

デバイス データを取得する前に、DirectInputDevice8.SetCooperativeLevel メソッドを使用して協調レベルを設定してから、DirectInputDevice8.SetCommonDataFormat を使用してデータ形式を設定し、DirectInputDevice8.Acquire メソッドを使用してデバイスを取得する必要がある。

参照

DirectInputDevice8.GetDeviceStateMouse2、DirectInputDevice8.Poll、ポーリングとイベント通知


DirectInputDevice8.GetDeviceStateMouse2

8 つまでのボタンを持つマウス デバイスから直接データを取得する。

object.GetDeviceStateMouse2(state As DIMOUSESTATE2)

指定項目

object
DirectInputDevice8 オブジェクトを指定する。
state
デバイスの状態を受け取る DIMOUSESTATE2 型。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかのエラー コードが設定される。

DIERR_INPUTLOST
DIERR_INVALIDPARAM
DIERR_NOTACQUIRED
E_PENDING

注意

デバイス データを取得する前に、DirectInputDevice8.SetCooperativeLevel メソッドを使用して協調レベルを設定してから、DirectInputDevice8.SetCommonDataFormat を使用してデータ形式を設定し、DirectInputDevice8.Acquire メソッドを使用してデバイスを取得する必要がある。

参照

DirectInputDevice8.GetDeviceStateMouse、DirectInputDevice8.Poll、ポーリングとイベント通知


DirectInputDevice8.GetEffectsEnum

標準のエフェクトやデバイス メーカーにより設計されたエフェクトなど、デバイスがサポートするフォース フィードバック エフェクトを列挙する。

object.GetEffectsEnum( _
  effType As CONST_DIEFTFLAGS _
) As DirectInputEnumEffects

指定項目

object
DirectInputDevice8 オブジェクトを指定する。
effType
列挙対象のエフェクト タイプを指定する CONST_DIEFTFLAGS 列挙のうち、次のいずれか 1 つのフラグ。

DIEFT_ALL
DIEFT_CONDITION
DIEFT_CONSTANTFORCE
DIEFT_CUSTOMFORCE
DIEFT_HARDWARE
DIEFT_PERIODIC
DIEFT_RAMPFORCE

戻り値

DirectInputEnumEffects オブジェクトが返される。このオブジェクトのメソッドは、エフェクトに関する情報の取得に使用する。

エラー コード

失敗した場合はエラーが発生し、Err.Number が設定される。


DirectInputDevice8.GetForceFeedbackState

デバイスのフォース フィードバック システムの状態を取得する。

object.GetForceFeedbackState() As CONST_DIGFFSFLAGS

指定項目

object
DirectInputDevice8 オブジェクトを指定する。

戻り値

成功すれば、デバイスのフォース フィードバック システムの現在の状態を表す CONST_DIGFFSFLAGS 列挙からのフラグが返される。

Microsoft® DirectInput® の将来のバージョンで、フラグが追加定義される可能性もある。アプリケーションは、現在未定義のフラグをすべて無視する必要がある。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかのエラー コードが設定される。

DIERR_INPUTLOST
DIERR_INVALIDPARAM
DIERR_NOTEXCLUSIVEACQUIRED
DIERR_NOTINITIALIZED
DIERR_UNSUPPORTED

注意

このメソッドを成功させるには、デバイスを排他協調レベルで取得しなければならない。


DirectInputDevice8.GetImageInfo

構成プロパティ シートで使用するデバイス イメージに関する情報を取得する。

object.GetImageInfo(info As DIDEVICEIMAGEINFOHEADER)

指定項目

object
DirectInputDevice8 オブジェクトを指定する。
info
デバイス イメージに関する情報を受け取る DIDEVICEIMAGEINFOHEADER 型。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかのエラー コードが設定される。

DIERR_INVALIDPARAM
DIERR_MAPFILEFAIL
DIERR_MOREDATA
DIERR_NOTINITIALIZED
DIERR_OBJECTNOTFOUND

参照

DirectInputDevice8.GetImageInfoCount


DirectInputDevice8.GetImageInfoCount

デバイスで使用可能なイメージ数を取得する。このメソッドを使って、DIDEVICEIMAGEINFOHEADER 型を DirectInputDevice8.GetImageInfo に渡す前に、いくつの配列要素を Images メンバに割り当てる必要があるかどうかを確認する。

object.GetImageInfoCount() As Long

指定項目

object
DirectInputDevice8 オブジェクトを指定する。

エラー コード

失敗した場合はエラーが発生し、Err.Number が設定される。


DirectInputDevice8.GetObjectInfo

ボタンや軸などのデバイス オブジェクトに関する情報を取得する。

object.GetObjectInfo( _
  obj As Long, _
  how As CONST_DIPHFLAGS) _
  As DirectInputDeviceObjectInstance

指定項目

object
DirectInputDevice8 オブジェクトを指定する。
obj
情報を取得するオブジェクトを識別する値。このパラメータの解釈は、how パラメータで指定されている値に依存する。
how
obj パラメータの解釈方法を指定する値。この値は、CONST_DIPHFLAGS 列挙の定数のいずれかを取ることができる。

戻り値

DirectInputDeviceObjectInstance オブジェクトが返される。このオブジェクトのメソッドを使って、オブジェクトに関する情報を取得する。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかのエラー コードが設定される。

DIERR_INVALIDPARAM
DIERR_OBJECTNOTFOUND


DirectInputDevice8.GetProperty

入力デバイスについての情報を取得する。

object.GetProperty( _
  guid As String, _
  propertyInfo As Any)

指定項目

object
DirectInputDevice8 オブジェクトを指定する。
guid
取得するプロパティの識別子。入力デバイスには次のプロパティが定義されており、文字列として渡すことができる。
DIPROP_AUTOCENTER
デバイス オブジェクトが自動センタリングを行うかどうかを指定する。詳細については、「DirectInputDevice8.SetProperty」を参照すること。
DIPROP_AXISMODE
軸モードを取得する。取得される値は DIPROPAXISMODE_ABS または DIPROPAXISMODE_REL である(列挙「CONST_DINPUT」を参照すること)。
DIPROP_BUFFERSIZE
入力バッファ サイズを取得する。バッファ サイズは、DirectInputDevice8.GetDeviceData メソッドの前回と今回の呼び出しの間で、バッファがデータを失うことなく保持できるデータの量を決定する。この値にゼロを設定して、アプリケーションがデバイスからバッファリング データを読み込まないように指定することもできる。
DIPROP_DEADZONE
0 ～ 10,000 の範囲でジョイスティックのデッド ゾーンの値を取得する。ここで、0 はデッド ゾーンが存在しないこと、5,000 はデッド ゾーンが軸を中心とした物理範囲の 50 パーセントにまで広がっていること、および 10,000 は軸の物理範囲の全体が無効であることをそれぞれ示す。軸がデッド ゾーン内にあると、軸の範囲の中心にあるものと報告される。
DIPROP_FFGAIN
デバイスのゲインを取得する。詳細については、「DirectInputDevice8.SetProperty」を参照すること。
DIPROP_FFLOAD
デバイスのメモリ ロードを取得する。この設定値は、個別のオブジェクトではなくデバイス全体に適用されるので、割り当てられた DIPROPLONG 型の lHow メンバは DIPH_DEVICE でなければならない。デバイスは排他モードで取得しなければならない。排他モードでない場合、このメソッドは失敗し、戻り値 DIERR_NOTEXCLUSIVEACQUIRED が返される。

lData メンバは、0 ～ 100 の範囲にある値を格納する。この値は、使用中のデバイス メモリのパーセント数を示す。

DIPROP_GRANULARITY
入力の細分度を取得する。細分度は、オブジェクトが移動を報告する最小距離を表す。多くの軸オブジェクトの細分度は 1 であり、あらゆる値を取ることができる。軸によっては、より大きな細分度を持つものもある。たとえば、マウスのホイール軸の細分度は 20 にすることもできる。報告される位置変化はすべて、20 の倍数となる。つまり、ユーザーがホイールをゆっくり回転させると、デバイスは位置を 0、20、40 などと報告する。

これは読み取り専用プロパティなので、DirectInputDevice8.SetProperty メソッドを呼び出しても、値を設定することはできない。

DIPROP_RANGE
オブジェクトが報告できる値の範囲を取得する。取得された最小値および最大値は、割り当てられた DIPROPRANGE 型の lMin および lMax メンバに設定される。

一部のデバイスでは、これは読み取り専用プロパティである。DirectInputDevice8.SetProperty メソッドを呼び出しても、値を設定することはできない。

DIPROP_SATURATION
0 ～ 10,000 の範囲でジョイスティックの飽和ゾーンの値を取得する。飽和レベルとは、軸が極限位置にあると見なされるポイントのことである。たとえば、飽和レベルが 9,500 に設定されている場合、軸の中心 (デッド ゾーン) から軸の端までの物理的距離の 95% の位置が軸の極限位置となる。
propertyInfo
単一の値を受け取る DIPROPLONG 型。または、1 組の値を受け取る DIPROPRANGE 型。この型の lObj、lHow、および lSize メンバは、メソッドを呼び出す前に初期化しなければならない。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかのエラー コードが設定される。

DIERR_INVALIDPARAM
DIERR_NOTEXCLUSIVEACQUIRED
DIERR_NOTINITIALIZED
DIERR_OBJECTNOTFOUND
DIERR_UNSUPPORTED

参照

DirectInputDevice8.SetProperty


DirectInputDevice8.Poll

Microsoft® DirectInput® デバイス上のポーリング対象オブジェクトからのデータを利用可能にする。デバイスにポーリングが必要ないときにこのメソッドを呼び出しても、効果は一切ない。ポーリングする必要があるデバイスが定期的にポーリングされない場合、このデバイスから新しいデータは取得されない。このメソッドを呼び出すと、Microsoft® DirectInput® はデバイス状態を更新し、バッファリング データが使用可能な場合は入力イベントを生成し、通知が有効であれば通知イベントを設定する。

object.Poll()

指定項目

object
DirectInputDevice8 オブジェクトを指定する。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかのエラー コードが設定される。

DIERR_INPUTLOST
DIERR_NOTACQUIRED

注意

デバイス データをポーリングする前に、DirectInputDevice8.SetDataFormat または DirectInputDevice8.SetCommonDataFormat メソッドでデータ形式を設定し、DirectInputDevice8.Acquire メソッドでデバイスを取得しなければならない。

参照

ポーリングとイベント通知


DirectInputDevice8.RunControlPanel

デバイスに関連付けられたコントロール パネルのプロパティ シートを開く。デバイスにプロパティ シートが関連付けられていない場合、デフォルトのプロパティが表示される。

object.RunControlPanel(hwnd As Long)

指定項目

object
DirectInputDevice8 オブジェクトを指定する。
hwnd
親ウィンドウのハンドル。このパラメータがゼロなら、親ウィンドウは使用されない。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかのエラー コードが設定される。

DIERR_INVALIDPARAM


DirectInputDevice8.SendDeviceData

出力を受け付けるデバイスにデータを送信する。デバイスは、取得済みの状態でなければならない。

object.SendDeviceData(count As Long, _
  data() As DIDEVICEOBJECTDATA, _
  flags As CONST_DESDDFLAGS) As Long

指定項目

object
DirectInputDevice8 オブジェクトを指定する。
count
data 内の要素数。
data
デバイスに送信するデータを格納した DIDEVICEOBJECTDATA 型の配列。

DIDEVICEOBJECTDATA 型の lOfs フィールドには、データの送信先であるデバイス オブジェクトのインスタンス識別子 (データ オフセットではない) を格納しなければならない (「DirectInputDeviceObjectInstance.GetType」を参照)。lTimeStamp メンバと lSequence メンバはゼロでなければならない。

flags
データの送信方法を制御するフラグ。ゼロまたは次の値を取ることができる。
DISDD_CONTINUE
送信されるデバイス データは、以前に送信されたデバイス データに上書きされる。「注意」を参照すること。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかのエラー コードが設定される。

DIERR_INPUTLOST
DIERR_NOTACQUIRED
DIERR_REPORTFULL
DIERR_UNPLUGGED

注意

個別のデータ要素が特定の順序で送信されるという保証はない。しかし、SendDeviceData の呼び出しが成功した場合、送信されたデータの間に別のデータが紛れ込むことはない。さらに、複数のデータが 1 回の呼び出しで同じオブジェクトに送信される場合、どのデータが送信されるかは特定されない。

たとえば、データをパケット単位で送信できるデバイスがあり、各パケットは、A および B という 2 つの情報を表すとする。ここで、アプリケーションが 3 つのデータ要素 (B = 2、A = 1、B =0) を送信しようとするとどうなるだろうか。

実際のデバイスに送信されるパケットは、1 つである。パケットの A フィールドの値は 1、そしてパケットの B フィールドの値は 2 か 0 になる。

データを指定どおりにデバイスに送信しなければならない場合は、SendDeviceData を 3 回呼び出し、呼び出しごとにデータ要素を 1 つずつ送信しなければならない。

最初の呼び出しに応答して、A フィールドがブランク、B フィールドの値が 2 のパケットをデバイスに送信する。

2 回目の呼び出しでは、A フィールドの値が 1、B フィールドがブランクのパケットを送信する。

最後の 3 回目の呼び出しで、A フィールドがブランク、B フィールドの値が 0 のパケットを送信する。

DISDD_CONTINUE が設定されている場合、送信されたデバイス データは以前に送信されたデバイス データに上書きされる。フラグの設定がなければ、送信されるデバイス データはまったく新しいものとして処理される。

たとえば、Button0 および Button1 の 2 つのボタン出力をサポートするデバイスがあるとする。アプリケーションが最初に SendDeviceData を呼び出して "Button0 押下" を渡すと、デバイスには、"Button0 押下、Button1 未押下" という形式のパケットが送信される。次に、アプリケーションがもう一度 SendDeviceData を呼び出して "Button1 押下" と DISDD_CONTINUE フラグを渡すと、デバイスには、"Button0 押下、Button1 押下" という形式のパケットが送信される。しかし、アプリケーションが DISDD_CONTINUE フラグを渡さなかった場合、デバイスに送信されるパケットは、"Button0 未押下、Button1 押下" となる。


DirectInputDevice8.SendForceFeedbackCommand

デバイスのフォース フィードバック システムにコマンドを送信する。

object.SendForceFeedbackCommand(flags As Long)

指定項目

object
DirectInputDevice8 オブジェクトを指定する。
flags
目的の状態変化を示す単一の値。この値は、CONST_DISFFCFLAGS 列挙のメンバのいずれかを取ることができる。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかのエラー コードが設定される。

DIERR_INPUTLOST
DIERR_NOTACQUIRED
DIERR_REPORTFULL
DIERR_UNPLUGGED


DirectInputDevice8.SetActionMap

デバイスのデータ形式を設定し、アプリケーション定義のアクションをデバイス オブジェクトにマップする。バッファリング データのバッファ サイズも設定する。

メモ

このメソッドを呼び出す前に、デバイスを解放しておく必要がある。

object.SetActionMap(format As DIACTIONFORMAT, _
  userName As String, _
  flags As Long)

指定項目

object
DirectInputDevice8 オブジェクトを指定する。
format
適用されるアクション マップに関する情報や、バッファリング デバイス データのバッファ サイズに関する情報を指定する DIACTIONFORMAT 型。
userName
ユーザー名を指定する文字列型の値。
flags
アクション マップの適用方法を指定する Long 型の値。この値は、CONST_DIDSAMFLAGS 列挙の定数のいずれかを取ることができる。

エラー コード

失敗すれば、Err.Number に次のエラー値のいずれかが設定される。

DIERR_ACQUIRED
DIERR_INVALIDPARAM

注意

このメソッドを使うことで、アクションとコントロールのマッピングをデバイスのデフォルトから変更できる。アプリケーションは、このメソッドを使ってアクションを仮想コントロールにマップする必要がある。

このメソッドに渡されるユーザー名により、デバイスのアクション マッピングのセットが特定ユーザーにバインドされる。設定が現在適用されているマップと異なる場合は、自動的にディスクに保存される。複数のユーザーから入力を受け付けるアプリケーションは、各ユーザーのアクション マップが競合する可能性があるので、システムのマウスやキーボードにアクション マップを適用する際は注意が必要である。

このメソッドはデバイスが取得されていない場合にのみ呼び出すことができる。

参照

DirectInputDevice8.BuildActionMap


DirectInputDevice8.SetCommonDataFormat

標準デバイスに入力データ形式を設定する。

object.SetCommonDataFormat( _
  format As CONST_DICOMMONDATAFORMATS)

指定項目

object
DirectInputDevice8 オブジェクトを指定する。
format
デバイスで使用されるデータ形式を識別する CONST_DICOMMONDATAFORMATS 列挙のいずれか。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかのエラー コードが設定される。

DIERR_ACQUIRED
DIERR_INVALIDPARAM

注意

DirectInputDevice8.Acquire メソッドでデバイスを取得する前に、データ形式を設定しなければならない。データ形式は、一度設定するだけでよい。データ形式は、デバイスが取得されている間は変更できない。

参照

DirectInputDevice8.SetDataFormat


DirectInputDevice8.SetCooperativeLevel

デバイスのインスタンスに協調レベルを設定する。協調レベルは、このインスタンスが、同じデバイスのほかのインスタンス、およびシステムのこれ以外の部分との間で、どのように対話するかを決める。

object.SetCooperativeLevel(hwnd As Long, _
  flags As CONST_DISCLFLAGS)

指定項目

object
DirectInputDevice8 オブジェクトを指定する。
hwnd
デバイスに関連付けられているウィンドウ ハンドル。このパラメータは、このプロセスに属する最上位の有効なウィンドウ ハンドルでなければならない。デバイスに関連付けられるウィンドウは、Microsoft® DirectInput® デバイスの中でアクティブである間は、破壊してはならない。
flags
デバイスに関連付ける協調レベルを表すフラグ。CONST_DISCLFLAGS 列挙の定数である。

次のフラグの組み合わせが有効である。
フラグ | 意味 | 対象
DISCL_NONEXCLUSIVE Or DISCL_BACKGROUND | ほかのアプリケーションは、排他モードまたは非排他モードにあるデバイスを取得できる。このアプリケーションは、データにいつでもアクセスできる。 | すべて。
DISCL_NONEXCLUSIVE Or DISCL_FOREGROUND | ほかのアプリケーションは、排他モードまたは非排他モードにあるデバイスを取得できる。このアプリケーションは、フォアグラウンドにあるときのみデータにアクセスできる。 | すべて。
DISCL_EXCLUSIVE Or DISCL_BACKGROUND | ほかのアプリケーションは、非排他モードにあるデバイスを取得できる。このアプリケーションは、データにいつでもアクセスできる。 | ジョイスティック。
DISCL_EXCLUSIVE Or DISC_FOREGROUND | ほかのアプリケーションは、非排他モードにあるデバイスを取得できる。このアプリケーションは、フォアグラウンドにあるときのみデータにアクセスできる。 | すべて。マウスの場合、有効だが Microsoft® Windows® はカーソルを表示できない。

キーボードの場合、Windows キーを無効にするには DISCL_NONEXCLUSIVE と共に DISCL_NOWINKEY も含める必要がある。DISCL_EXCLUSIVE が指定される場合、Windows キーは常に無効である。ただし、デフォルトのアクション マッピング UI が表示されている間は DISCL_NOWINKEY フラグは無効であり、また、デフォルトのアクション マッピング UI が存在している間は Windows キーは通常どおり機能する。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかのエラー コードが設定される。

DIERR_INVALIDPARAM
DIERR_INVALIDHANDLE

注意

2 つのアプリケーション (または同一アプリケーションの 2 つのインスタンス) が同時に 1 つのデバイスを排他モードで取得することはできない。これは主にセキュリティ面での機能である。これにより、1 つのアプリケーションからの入力が、同時に実行されている別のアプリケーションに流れることはない。

システム マウスが排他モードで取得されると、マウス ポインタは、デバイスが解放されるまで画面から消去される。

アプリケーションは、DirectInputDevice8.Acquire メソッドでデバイスを取得する前に、このメソッドを呼び出す必要がある。

参照

「協調レベル」


DirectInputDevice8.SetDataFormat

非標準のマウス、キーボード、ジョイスティックなどの Microsoft® DirectInput® デバイスに、データ形式を設定する。

object.SetDataFormat(format As DIDATAFORMAT, _
  formatArray() As DIOBJECTDATAFORMAT))

指定項目

object
DirectInputDevice8 オブジェクトを指定する。
format
デバイスが返すデータ形式を表す DIDATAFORMAT 型。
formatArray
デバイス上のオブジェクトのデータ形式を表す DIOBJECTDATAFORMAT 型の配列。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかのエラー コードが設定される。

DIERR_ACQUIRED
DIERR_INVALIDPARAM

注意

DirectInputDevice8.Acquire メソッドでデバイスを取得する前に、データ形式を設定しなければならない。データ形式は、一度設定するだけでよい。データ形式は、デバイスが取得されている間は変更できない。

参照

DirectInputDevice8.SetActionMap、DirectInputDevice8.SetCommonDataFormat


DirectInputDevice8.SetEventNotification

イベント通知ステータスを設定する。このメソッドは、デバイス状態が変化したときに設定されるイベントを指定する。イベント通知をオフにするためにも使用される。

object.SetEventNotification(hEvent As Long)

指定項目

object
DirectInputDevice8 オブジェクトを指定する。
hEvent
デバイス状態が変化したときに設定されるイベントのハンドル。通知を無効にするにはゼロを設定する。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかのエラー コードが設定される。

DIERR_ACQUIRED
DIERR_HANDLEEXISTS
DIERR_INVALIDPARAM

注意

デバイス状態の変更は次のいずれかに定義される。

  • 軸の位置の変更
  • ボタンの状態 (押した状態または離した状態)
  • 視点コントロールの方向の変更
  • 取得の喪失

イベント ハンドルを破壊する前に、hEvent パラメータにゼロを設定して、このメソッドを呼び出さなければならない。

イベント通知ハンドルは、デバイスが取得されている間は変更できない。

参照

「ポーリングとイベント通知」、DirectXEvent8


DirectInputDevice8.SetProperty

デバイスの動作を定義するプロパティを設定する。

object.SetProperty( _
  guid As String, _
  propertyInfo As Any)

指定項目

object
DirectInputDevice8 オブジェクトを指定する。
guid
設定対象のプロパティの識別子。入力デバイスには次のプロパティ値が定義されており、文字列として渡すことができる。
DIPROP_AUTOCENTER
デバイス オブジェクトが自動センタリングを行うかどうかを指定する。この設定値は、個別のオブジェクトではなくデバイス全体に適用されるので、割り当てられた DIPROPLONG 型の lHow メンバは DIPH_DEVICE でなければならない。

lData メンバは、次の CONST_DINPUT 列挙のいずれか 1 つの値でなければならない。

DIPROPAUTOCENTER_OFF:ユーザーがデバイスを離しても、自動的にセンタリングを行わない。フォース フィードバックを使用するアプリケーションは、エフェクトの再生前に自動センタリングを無効にする必要がある。

DIPROPAUTOCENTER_ON:ユーザーがデバイスを離すと、自動的にセンタリングを行う。

自動センタリング機能をサポートしていないデバイスもある。

DIPROP_AXISMODE
軸モードを設定する。設定値 (CONST_DINPUT 列挙の DIPROPAXISMODE_ABS または DIPROPAXISMODE_REL) は、割り当てられた DIPROPLONG 型の lData メンバに指定しなければならない。

この設定値はデバイス全体に適用されるので、割り当てられた DIPROPLONG 型の lHow メンバは DIPH_DEVICE でなければならない

DIPROP_BUFFERSIZE
入力バッファ サイズを設定する。「注意」を参照すること。

この設定値はデバイス全体に適用されるので、割り当てられた DIPROPLONG 型の lHow メンバは DIPH_DEVICE でなければならない

DIPROP_CALIBRATIONMODE
Microsoft® DirectInput® が取得するデータが、キャリブレーション済みかキャリブレーション前かをアプリケーションが指定できるようにする。デフォルトでは、DirectInput はキャリブレーション済みデータを取得する。

デバイス全体に対してキャリブレーション モードを設定することは、それぞれの軸に対してキャリブレーション モードを設定することと同じ意味を持つ。

DIPROPLONG 型の lData メンバは次のいずれか 1 つの値を取ることができる。

DIPROPCALIBRATIONMODE_COOKED:DirectInput は、キャリブレーション情報の適用後のデータを返す。これがデフォルト モードである。

DIPROPCALIBRATIONMODE_RAW:DirectInput は、キャリブレーション前の未加工データを返す。このモードは通常、コントロール パネル型のアプリケーションでのみ使用される。

デバイスを未加工モードに設定すると、デッド ゾーン、飽和値、および範囲の設定が無視される。

DIPROP_DEADZONE
0 ～ 10,000 の範囲でジョイスティックのデッド ゾーンの値を設定する。ここで、0 はデッド ゾーンが存在しないこと、5,000 はデッド ゾーンが軸を中心とした物理範囲の 50 パーセントにまで広がっていること、および 10,000 は軸の物理範囲の全体が無効であることをそれぞれ示す。軸がデッド ゾーン内にあると、軸の範囲の中心にあるものと報告される。

この設定は、デバイス全体または 1 つの特定の軸のどちらかに適用できる。

DIPROP_RANGE
オブジェクトが報告可能な値の範囲を設定する。最小値および最大値は、割り当てられた DIPROPRANGE 型の lMin メンバと lMax メンバから取得される。

一部のデバイスでは、これは読み取り専用プロパティである。

範囲の大小を逆にはできない。lMax は、lMin より大きくなければならない。

DIPROP_SATURATION
0 ～ 10,000 の範囲でジョイスティックの飽和ゾーンの値を設定する。飽和レベルとは、軸が極限位置にあると見なされるポイントのことである。たとえば、飽和レベルが 9,500 に設定されている場合、軸の中心 (デッド ゾーン) から軸の端までの物理的距離の 95% の位置が軸の極限位置となる。

この設定は、デバイス全体または 1 つの特定の軸のどちらかに適用できる。

propertyInfo
単一の値を取るプロパティのデータを格納する DIPROPLONG 型。または、1 組の値を取るプロパティのデータを格納する DIPROPRANGE 型。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかのエラー コードが設定される。

DIERR_INVALIDPARAM
DIERR_OBJECTNOTFOUND
DIERR_UNSUPPORTED

注意

バッファ サイズは、DirectInputDevice8.GetDeviceData メソッドの前回と今回の呼び出しの間で、バッファがデータを失うことなく保持できるデータの量を決定する。この値にゼロを設定して、アプリケーションがデバイスからバッファリング データを読み込まないように指定することもできる。DIPROPLONG 型の lData メンバ中のバッファ サイズが大きすぎてデバイスがサポートできない場合は、サポート可能な最大バッファ サイズが設定される。要求したバッファ サイズが設定されたかどうかを確認するには、バッファ サイズ プロパティを取得して、設定しようとした値とその結果を比較する。

参照

DirectInputDevice8.GetProperty


DirectInputDevice8.Unacquire

デバイスへのアクセス権を解放する。

object.Unacquire()

指定項目

object
DirectInputDevice8 オブジェクトを指定する。

エラー コード

なし。

参照

DirectInputDevice8.Acquire


DirectInputDevice8.WriteEffectToFile

フォース フィードバック エフェクトをファイルに書き込む。

object.WriteEffectToFile( _
  filename As String, _
  flags As Long, _
  guid As String, _
  name As String, _
  CoverEffect As DIEFFECT)

指定項目

object
DirectInputDevice8 オブジェクトを指定する。
filename
RIFF ファイルの名前。同名のファイルが存在する場合は上書きされる。
flags
エフェクトの記述方法を制御するフラグ。次の CONST_DIFEFFLAGS 列挙のいずれか 1 つの値を使用できる。

DIFEF_DEFAULT

標準タイプ以外のエフェクトは記述しない。

DIFEF_INCLUDENONSTANDARD

標準タイプ以外のエフェクトも記述する。

guid
"GUID_RampForce" など、エフェクト タイプの識別子。標準エフェクトのリストについては、「DirectInputDevice8.CreateEffect」を参照すること。非標準のエフェクトの場合、このパラメータは数値のGUID を表す文字列でなければならない。
name
エフェクトの登録名。
CoverEffect
エフェクトのパラメータを指定する DIEFFECT 型。

エラー コード

失敗した場合はエラーが発生し、Err.Number に次のいずれかのエラー コードが設定される。

DIERR_INVALIDPARAM

注意

これは主に、独自フォースを作成するアプリケーション向けのメソッドである。

参照

DirectInputDevice8.CreateEffectFromFile


DirectInputDeviceInstance8

DirectInputDeviceInstance8 クラスは、Microsoft® DirectInput® デバイスのインスタンスに関する情報の取得に使用される。

このクラスのオブジェクトは、DirectInputDevice8.GetDeviceInfo メソッドと DirectInputEnumDevices8.GetItem メソッドにより返される。

DirectInputDeviceInstance8 クラスには、次のメソッドがある。

情報 | GetDevType
 | GetGuidFFDriver
 | GetGuidInstance
 | GetGuidProduct
 | GetInstanceName
 | GetProductName
 | GetUsage
 | GetUsagePage


DirectInputDeviceInstance8.GetDevType

デバイスのタイプとサブタイプを取得する。

object.GetDevType() As Long

指定項目

object
DirectInputDeviceInstance8 オブジェクトを指定する。

戻り値

デバイス タイプ指定子が返される。この値は、タイプ (最下位バイト) とサブタイプの組み合わせ (最下位から 1 つ上位のバイト) であり、オプションで Or を使って DIDEVTYPE_HID を組み合わせられる。このフラグは HID (Human Interface Device) を指定する。以下は、CONST_DI8DEVICETYPE および CONST_DI8DEVICESUBTYPE 列挙の定数である。

DI8DEVTYPE_1STPERSON
対面型のアクション ゲーム デバイス。次のサブタイプが定義される。
DI8DEVTYPE1STPERSON_LIMITED
アクション マッピング対象のデバイス オブジェクトの最小数を指定しないデバイス。
DI8DEVTYPE1STPERSON_SHOOTER
対面型のシューティング ゲーム用に設計されたデバイス。
DI8DEVTYPE1STPERSON_SIXDOF
6 段階 (3 つの横方向軸と 3 つの回転軸) の自由を備えたデバイス。
DI8DEVTYPE1STPERSON_UNKNOWN
不明なサブタイプ。
DI8DEVTYPE_DEVICE
別のカテゴリに属さないデバイス。
DI8DEVTYPE_DEVICECTRL
アプリケーションのコンテキストから別タイプのデバイスの制御に使用される入力デバイス。次のサブタイプが定義される。
DI8DEVTYPEDEVICECTRL_COMMSSELECTION
通信の選択に使用されるコントロール。
DI8DEVTYPEDEVICECTRL_HARDWIRED
デフォルトの構成を使用する必要があるデバイス。このデバイスは再マップできない。
DI8DEVTYPEDEVICECTRL_UNKNOWN
不明なサブタイプ。
DI8DEVTYPE_DRIVING
ステアリング用デバイス。次のサブタイプが定義される。
DI8DEVTYPEDRIVING_COMBINEDPEDALS
単一の軸からアクセルとブレーキ ペダルの値を報告するステアリング デバイス。
DI8DEVTYPEDRIVING_DUALPEDALS
別々の軸からアクセルとブレーキ ペダルの値を報告するステアリング デバイス。
DI8DEVTYPEDRIVING_HANDHELD
ハンドヘルドのステアリング デバイス。
DI8DEVTYPEDRIVING_THREEPEDALS
別々の軸からアクセル、ブレーキ、およびクラッチ ペダルの値を報告するステアリング デバイス。
DI8DEVTYPE_FLIGHT
フライト シミュレーション用コントローラ。次のサブタイプが定義される。
DI8DEVTYPEFLIGHT_LIMITED
アクション マッピング対象のデバイス オブジェクトの最小数を指定しないフライト コントローラ。
DI8DEVTYPEFLIGHT_RC
模型飛行機のリモート コントロールに基づくフライト デバイス。
DI8DEVTYPEFLIGHT_STICK
ジョイスティック。
DI8DEVTYPEFLIGHT_YOKE
操縦輪。
DI8DEVTYPE_GAMEPAD
ゲームパッド。次のサブタイプが定義される。
DI8DEVTYPEGAMEPAD_LIMITED
アクション マッピング対象のデバイス オブジェクトの最小数を指定しないゲームパッド。
DI8DEVTYPEGAMEPAD_STANDARD
アクション マッピング対象のデバイス オブジェクトの最小数を指定しない標準ゲームパッド。
DI8DEVTYPEGAMEPAD_TILT
コントローラの姿勢から x 軸と y 軸のデータを報告するゲームパッド。
DI8DEVTYPE_JOYSTICK
ジョイスティック。次のサブタイプが定義される。
DI8DEVTYPEJOYSTICK_LIMITED
アクション マッピング対象のデバイス オブジェクトの最小数を指定しないジョイスティック。
DI8DEVTYPEGAMEPAD_STANDARD
アクション マッピング対象のデバイス オブジェクトの最小数を指定しない標準ゲームパッド。
DI8DEVTYPEJOYSTICK_STANDARD
アクション マッピング対象のデバイス オブジェクトの最小数を指定する標準ジョイスティック。
DI8DEVTYPE_KEYBOARD
キーボードまたはキーボード類似デバイス。次のサブタイプが定義される。
DI8DEVTYPEKEYBOARD_UNKNOWN
サブタイプは確定できない。
DI8DEVTYPEKEYBOARD_PCXT
IBM PC/XT 83 キー キーボード。
DI8DEVTYPEKEYBOARD_OLIVETTI
Olivetti 102 キー キーボード。
DI8DEVTYPEKEYBOARD_PCAT
IBM PC/AT 84 キー キーボード。
DI8DEVTYPEKEYBOARD_PCENH
IBM PC 拡張 101/102 キー式キーボードまたは Microsoft® ナチュラル キーボード
DI8DEVTYPEKEYBOARD_NOKIA1050
Nokia 1050 キーボード。
DI8DEVTYPEKEYBOARD_NOKIA9140
Nokia 9140 キーボード。
DI8DEVTYPEKEYBOARD_NEC98
日本語 NEC PC98 キーボード。
DI8DEVTYPEKEYBOARD_NEC98LAPTOP
日本語 NEC PC98 ラップトップ キーボード。
DI8DEVTYPEKEYBOARD_NEC98106
日本語 NEC PC98 106 キー キーボード。
DI8DEVTYPEKEYBOARD_JAPAN106
日本語 106 キー キーボード。
DI8DEVTYPEKEYBOARD_JAPANAX
日本語 AX キーボード。
DI8DEVTYPEKEYBOARD_J3100
日本語 J3100 キーボード。
DI8DEVTYPE_MOUSE
マウスまたはマウス類似デバイス (トラックボールなど)。次のサブタイプが定義される。
DI8DEVTYPEMOUSE_ABSOLUTE
絶対軸データを返すマウス。
DI8DEVTYPEMOUSE_FINGERSTICK
フィンガースティック。
DI8DEVTYPEMOUSE_TOUCHPAD
タッチパッド。
DI8DEVTYPEMOUSE_TRACKBALL
トラックボール。
DI8DEVTYPEMOUSE_TRADITIONAL
従来型マウス。
DI8DEVTYPEMOUSE_UNKNOWN
サブタイプは確定できない。
DI8DEVTYPE_REMOTE
リモート コントロール デバイス。定義済みのサブタイプは DI8DEVTYPEREMOTE_UNKNOWN のみである。
DI8DEVTYPE_SCREENPOINTER
スクリーン ポインタ。次のサブタイプが定義される。
DI8DEVTYPESCREENPTR_UNKNOWN
不明なサブタイプ。
DI8DEVTYPESCREENPTR_LIGHTGUN
ライト ガン。
DI8DEVTYPESCREENPTR_LIGHTPEN
ライト ペン。
DI8DEVTYPESCREENPTR_TOUCH
タッチ スクリーン。
DI8DEVTYPE_SUPPLEMENTAL
ホイールと共に使用するペダルなど、アプリケーションのメイン コントロールに適さない機能を備えた特殊デバイス。次のサブタイプが定義される。
DI8DEVTYPESUPPLEMENTAL_2NDHANDCONTROLLER
2 次的ハンドヘルド コントローラ。
DI8DEVTYPESUPPLEMENTAL_COMBINEDPEDALS
主機能として、単一の軸からアクセルとブレーキ ペダルの値を報告するデバイス。
DI8DEVTYPESUPPLEMENTAL_DUALPEDALS
主機能として、別々の軸からアクセルとブレーキ ペダルの値を報告するデバイス。
DI8DEVTYPESUPPLEMENTAL_HANDTRACKER
手の移動を追跡するデバイス。
DI8DEVTYPESUPPLEMENTAL_HEADTRACKER
頭の移動を追跡するデバイス。
DI8DEVTYPESUPPLEMENTAL_RUDDERPEDALS
方向舵ペダルを備えたデバイス。
DI8DEVTYPESUPPLEMENTAL_SHIFTER
軸からギア選択を報告するデバイス。
DI8DEVTYPESUPPLEMENTAL_SHIFTSTICKGATE
ボタン状態からギア選択を報告するデバイス。
DI8DEVTYPESUPPLEMENTAL_SPLITTHROTTLE
主機能として、2 つ以上のスロットル値を報告するデバイス。その他のコントロールを持つ場合がある。
DI8DEVTYPESUPPLEMENTAL_THREEPEDALS
主機能として、別々の軸からアクセル、ブレーキ、およびクラッチ ペダルの値を報告するデバイス。
DI8DEVTYPESUPPLEMENTAL_THROTTLE
主機能として、単一のスロットル値を報告するデバイス。その他のコントロールを持つ場合がある。
DI8DEVTYPESUPPLEMENTAL_UNKNOWN
不明なサブタイプ。

エラー コード

失敗した場合はエラーが発生し、Err.Number が設定される。

注意

ホイールなど、デバイスの特定のサブタイプを探すには、タイプとサブタイプの両方をチェックする必要がある。


DirectInputDeviceInstance8.GetGuidFFDriver

フォース フィードバック ドライバの一意な識別子を取得する。

object.GetGuidFFDriver() As String

指定項目

object
DirectInputDeviceInstance8 オブジェクトを指定する。

戻り値

フォース フィードバック ドライバの GUID が文字列形式で返される。この識別子は、ドライバのメーカーが定める。

エラー コード

失敗した場合はエラーが発生し、Err.Number が設定される。

参照

GUID の使い方


DirectInputDeviceInstance8.GetGuidInstance

デバイスのインスタンスに対する一意な識別子を取得する。

object.GetGuidInstance() As String

指定項目

object
DirectInputDeviceInstance8 オブジェクトを指定する。

戻り値

デバイス インスタンスの GUID が文字列形式で返される。

エラー コード

失敗した場合はエラーが発生し、Err.Number が設定される。

注意

アプリケーションは、このインスタンス GUID を構成ファイルに保存し、後で使用することもできる。インスタンス GUID は、コンピュータごとに固有である。1 つのコンピュータから取得されるインスタンス GUID は、ほかのコンピュータ上のインスタンス GUID とは無関係である。

参照

DirectInputDeviceInstance8.GetGuidProduct、「GUID の使い方」


DirectInputDeviceInstance8.GetGuidProduct

デバイスに対するメーカーの一意な識別子を取得する。

object.GetGuidProduct() As String

指定項目

object
DirectInputDeviceInstance8 オブジェクトを指定する。

戻り値

製品の GUID が文字列形式で返される。この識別子は、デバイス メーカーが定める。

エラー コード

失敗した場合はエラーが発生し、Err.Number が設定される。

参照

DirectInputDeviceInstance8.GetGuidInstance、「GUID の使い方」


DirectInputDeviceInstance8.GetInstanceName

デバイス インスタンスの名前を取得する。

object.GetInstanceName() As String

指定項目

object
DirectInputDeviceInstance8 オブジェクトを指定する。

戻り値

インスタンスの登録名が返される。たとえば、"Joystick 1" など。

エラー コード

失敗した場合はエラーが発生し、Err.Number が設定される。

参照

DirectInputDeviceInstance8.GetProductName


DirectInputDeviceInstance8.GetProductName

デバイスの製品名を取得する。

object.GetProductName() As String

指定項目

object
DirectInputDeviceInstance8 オブジェクトを指定する。

戻り値

製品の登録名が返される。たとえば、"Microsoft® SideWinder®" など。

エラー コード

失敗した場合はエラーが発生し、Err.Number が設定される。

参照

DirectInputDeviceInstance8.GetInstanceName


DirectInputDeviceInstance8.GetUsage

HID (Human Interface Device) の使用コードを取得する。

object.GetUsage() As Integer

指定項目

object
DirectInputDeviceInstance8 オブジェクトを指定する。

戻り値

HID デバイスの HID 使用コードを返す。HID デバイスでない場合は 0 を返す。

エラー コード

失敗した場合はエラーが発生し、Err.Number が設定される。

参照

DirectInputDeviceInstance8.GetUsagePage


DirectInputDeviceInstance8.GetUsagePage

HID (Human Interface Device) の使用ページを取得する。

object.GetUsagePage() As Integer

指定項目

object
DirectInputDeviceInstance8 オブジェクトを指定する。

戻り値

HID の使用ページを返す。HID でない場合は 0 を返す。

エラー コード

失敗した場合はエラーが発生し、Err.Number が設定される。

参照

DirectInputDeviceInstance8.GetUsage


DirectInputDeviceObjectInstance

DirectInputDeviceObjectInstance クラスは、ボタンや軸など、Microsoft® DirectInput® デバイス上のオブジェクトを表す。

DirectInputDeviceObjectInstance オブジェクトは、DirectInputDevice8.GetObjectInfo メソッドと DirectInputEnumDeviceObjects.GetItem メソッドにより返される。

このクラスには、次のメソッドがある。

情報 | GetCollectionNumber
 | GetDesignatorIndex
 | GetDimension
 | GetExponent
 | GetFlags
 | GetGuidType
 | GetName
 | GetOfs
 | GetType
 | GetUsage
 | GetUsagePage


DirectInputDeviceObjectInstance.GetCollectionNumber

デバイス オブジェクトの所属先である HID リンク コレクションの番号を取得する。

object.GetCollectionNumber() As Integer

指定項目

object
DirectInputDeviceObjectInstance オブジェクトを指定する。

戻り値

HID リンク コレクションの番号を返す。オブジェクトが HID に属していない場合は 0 を返す。

エラー コード

失敗した場合はエラーが発生し、Err.Number が設定される。


DirectInputDeviceObjectInstance.GetDesignatorIndex

HID (Human Interface Device) 上のオブジェクトの指定インデックスを取得する。

object.GetDesignatorIndex() As Integer

指定項目

object
DirectInputDeviceObjectInstance オブジェクトを指定する。

戻り値

HID 物理記述子の指定を参照するインデックスが返される。

エラー コード

失敗した場合はエラーが発生し、Err.Number が設定される。


DirectInputDeviceObjectInstance.GetDimension

オブジェクトの値を報告する次元単位に対する HID (Human Interface Device) コードを取得する。

object.GetDimension() As Long

指定項目

object
DirectInputDeviceObjectInstance オブジェクトを指定する。

戻り値

オブジェクトの値を報告する次元単位のコードが返される (判明している場合)。不明な場合はゼロとなる。

エラー コード

失敗した場合はエラーが発生し、Err.Number が設定される。

参照

DirectInputDeviceObjectInstance.GetExponent


DirectInputDeviceObjectInstance.GetExponent

デバイス オブジェクトの次元単位に関連付ける指数を取得する。

object.GetExponent() As Integer

指定項目

object
DirectInputDeviceObjectInstance オブジェクトを指定する。

戻り値

単位に付ける指数が返される (判明している場合)。次元単位は常に整数であるので、整数以外の型に単位を変換するには指数が必要となる。

エラー コード

失敗した場合はエラーが発生し、Err.Number が設定される。

参照

DirectInputDeviceObjectInstance.GetDimension


DirectInputDeviceObjectInstance.GetFlags

デバイス オブジェクトに関連付けられたフラグを取得する。

object.GetFlags() As CONST_DIDEVICEOBJINSTANCEFLAGS

指定項目

object
DirectInputDeviceObjectInstance オブジェクトを指定する。

戻り値

CONST_DIDEVICEOBJINSTANCEFLAGS 列挙の 1 つ以上のメンバが返される。

エラー コード

失敗した場合はエラーが発生し、Err.Number が設定される。


DirectInputDeviceObjectInstance.GetGuidType

オブジェクト タイプの一意な識別子を取得する。

object.GetGuidType() As String

指定項目

object
DirectInputDeviceObjectInstance オブジェクトを指定する。

戻り値

オブジェクト タイプの一意な識別子を表す次の文字列識別子のいずれかが返される。オブジェクト タイプが次の一覧にない GUID を持つ場合、実際の GUID を表す文字列が返される。オブジェクト タイプが GUID を持たない場合、空の文字列が返される。

GUID_XAxis
水平軸。たとえば、マウスの左右の動きを表すことができる。
GUID_YAxis
垂直軸。たとえば、マウスの前後の動きを表すことができる。
GUID_ZAxis
z 軸。たとえば、マウス上のホイールの回転、またはジョイスティックのスロットル制御の移動を表すことができる。
GUID_RxAxis
x 軸を中心とする回転。
GUID_RyAxis
y 軸を中心とする回転。
GUID_RzAxis
z 軸を中心とする回転 (方向舵のコントロールでよく使われる)。
GUID_Slider
スライダ軸
GUID_Button
マウスのボタン。
GUID_Key
キーボード上のキー。
GUID_POV
視点インジケータまたは視点ハット
GUID_Unknown
確定できない。

エラー コード

失敗した場合はエラーが発生し、Err.Number が設定される。


DirectInputDeviceObjectInstance.GetName

デバイス オブジェクトの登録名を取得する。

object.GetName() As String

指定項目

object
DirectInputDeviceObjectInstance オブジェクトを指定する。

戻り値

オブジェクトの名前が返される。たとえば、"X-Axis" または "Right Shift" など。

エラー コード

失敗した場合はエラーが発生し、Err.Number が設定される。


DirectInputDeviceObjectInstance.GetOfs

デバイスのデータ形式内におけるデバイス オブジェクト データのオフセットを取得する。

object.GetOfs() As Long

指定項目

object
DirectInputDeviceObjectInstance オブジェクトを指定する。

戻り値

データ形式内のオフセットで、このオブジェクトに報告されるデータの位置が返される。この値は、メソッド呼び出しにおけるオブジェクトと、DIPH_BYOFFSET フラグを受け取るタイプ内のオブジェクトを識別するために使用される。

エラー コード

失敗した場合はエラーが発生し、Err.Number が設定される。

参照

DirectInputDevice8.GetObjectInfo、DIPROPLONG、DIPROPRANGE


DirectInputDeviceObjectInstance.GetType

オブジェクトのタイプとインスタンス識別子を取得する。

object.GetType() As Long

指定項目

object
DirectInputDeviceObjectInstance オブジェクトを指定する。

戻り値

オブジェクトを表すデバイス タイプが返される。この値は、オブジェクト タイプ (軸、ボタンなど) を表す CONST_DIDFTFLAGS フラグの組み合わせであり、中央の 16 ビットには、オブジェクト インスタンス番号が格納される。

エラー コード

失敗した場合はエラーが発生し、Err.Number が設定される。

注意

オブジェクト インスタンス ID を取得するには、次の処理を実行する。

Dim ObjID as Long
ObjID = (diObj.GetType And &HFFFF00) \ 256


DirectInputDeviceObjectInstance.GetUsage

デバイス オブジェクトの HID (Human Interface Device) 使用コードを取得する。

object.GetUsage() As Integer

指定項目

object
DirectInputDeviceObjectInstance オブジェクトを指定する。

戻り値

オブジェクトに関連する HID 使用状況が返される (判明した場合)。HID は常に使用状況を報告する。非 HID デバイスは使用状況を報告するとは限らない。非 HID デバイスが報告しない場合、このパラメータの値はゼロになる。

エラー コード

失敗した場合はエラーが発生し、Err.Number が設定される。

参照

DirectInputDeviceObjectInstance.GetUsagePage


DirectInputDeviceObjectInstance.GetUsagePage

デバイス オブジェクトの HID (Human Interface Device) 使用ページを取得する。

object.GetUsagePage() As Integer

指定項目

object
DirectInputDeviceObjectInstance オブジェクトを指定する。

戻り値

オブジェクトに関連する HID 使用ページが返される (判明した場合)。HID は常に使用ページを報告する。非 HID デバイスは使用ページを報告するとは限らない。非 HID デバイスが報告しない場合、このパラメータの値はゼロになる。

エラー コード

失敗した場合はエラーが発生し、Err.Number が設定される。

参照

DirectInputDeviceObjectInstance.GetUsage


DirectInputEffect

DirectInputEffect クラスのオブジェクトは、アプリケーションが生成するフォース フィードバック エフェクトを表す。オブジェクトを作成するには、DirectInputDevice8.CreateEffect メソッドを使用する。

このクラスには、次のメソッドがある。

コントロール | Download
 | SetParameters
 | Start
 | Stop
 | Unload
情報 | GetEffectGuid
 | GetEffectStatus
 | GetParameters


DirectInputEffect.Download

デバイスにエフェクトを設定する。そのエフェクトがデバイス上に既に存在する場合、DirectInputEffect.SetParameters メソッドで設定された値に一致するように、既存のエフェクトが更新される。

object.Download()

指定項目

object
DirectInputEffect オブジェクトを指定する。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかのエラー コードが設定される。

DIERR_NOTINITIALIZED
DIERR_DEVICEFULL
DIERR_INCOMPLETEEFFECT
DIERR_INPUTLOST
DIERR_NOTEXCLUSIVEACQUIRED
DIERR_INVALIDPARAM
DIERR_EFFECTPLAYING

注意

このメソッドを成功させるには、デバイスを排他協調レベルで取得しなければならない。

エフェクトの再生中にエフェクトを更新することは有効である。この操作の意味については、DirectInputEffect.SetParameters の説明を参照すること。


DirectInputEffect.GetEffectGuid

DirectInputEffect オブジェクトが表すエフェクトの GUID または GUID エイリアスを取得する。

object.GetEffectGuid() As String

指定項目

object
DirectInputEffect オブジェクトを指定する。

戻り値

DirectInputDevice8.CreateEffect に渡す GUID またはエイリアスが返される (たとえば、"GUID_ConstantForce" など)。

エラー コード

失敗した場合はエラーが発生し、Err.Number が設定される。

参照

GUID の使い方


DirectInputEffect.GetEffectStatus

エフェクトのステータスを取得する。

object.GetEffectStatus() As Long

指定項目

object
DirectInputEffect オブジェクトを指定する。

戻り値

エフェクトのステータス フラグが返される。値はゼロか、次の CONST_DIEGESFLAGS 列挙の定数のいずれかを取ることができる。

DIEGES_PLAYING
エフェクトは再生中である。
DIEGES_EMULATED
エフェクトはエミュレートされる。

エラー コード

失敗した場合はエラーが発生し、Err.Number が設定される。


DirectInputEffect.GetParameters

エフェクトに関する情報を取得する。

object.GetParameters(effectinfo As DIEFFECT)

指定項目

object
DirectInputEffect オブジェクトを指定する。
effectinfo
エフェクト パラメータを受け取る DIEFFECT 型。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかのエラー コードが設定される。

DIERR_INVALIDPARAM
DIERR_MOREDATA
DIERR_NOTINITIALIZED


DirectInputEffect.SetParameters

エフェクトの特性を設定する。

object.SetParameters(effectinfo As DIEFFECT, _
    flags As CONST_DIEPFLAGS)

指定項目

object
DirectInputEffect オブジェクトを指定する。
effectinfo
エフェクト パラメータを格納する DIEFFECT 型。
flags
エフェクト情報のどの部分を設定するか、パラメータのダウンロードをどのように処理するかを指定する、CONST_DIEPFLAGS 列挙からのフラグ。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかのエラー コードが設定される。

DIERR_NOTINITIALIZED
DIERR_INCOMPLETEEFFECT
DIERR_INPUTLOST
DIERR_INVALIDPARAM
DIERR_EFFECTPLAYING

注意

どのパラメータがエフェクトの再生中に動的に更新できるかを判定するには、DirectInputEnumEffects.GetDynamicParams メソッドを使用する。

DirectInputEffect.SetParameters メソッドは、自動的にエフェクトをダウンロードするが、この動作は、DIEP_NODOWNLOAD フラグを設定することによって抑制できる。自動ダウンロードが抑制されていた場合、DirectInputEffect.Download を呼び出してエフェクトを手動でダウンロードできる。

エフェクトの再生中にパラメータが更新されると、エフェクトの開始時のパラメータであったかのように、新しいパラメータが有効になる。

たとえば、3 秒の継続時間を持つ周期的エフェクトが開始されているとする。2 秒後に、エフェクトの方向が変更される。その後、エフェクトは残りの 1 秒間は新しい方向で継続される。エンベロープ、フェーズ、振幅などのエフェクトのパラメータは、方向が変更されなかったかのように続行される。

先の例と同じ状況で、今度は 2 秒後にエフェクトの継続時間が 1.5 秒に変更されたとすると、エフェクトは停止する。

通常、ドライバが再生中のエフェクトのパラメータを更新できない場合、ドライバはそのエフェクトを停止し、パラメータを更新してからそのエフェクトを再開することができる。DIEP_NORESTART フラグを渡すと、この処理が抑制される。エフェクトの再生中にドライバがエフェクトのパラメータを更新できないときは、エラー コードの DIERR_EFFECTPLAYING が返され、パラメータは更新されない。

フラグ DIEP_NODOWNLOAD、DIEP_START、DIEP_NORESTART のうち同時に 2 つ以上を設定してはいけない(何も渡さなくてもよい)。

この 3 つのフラグは、次に示すように、ダウンロード処理と再生処理を制御する。

DIEP_NODOWNLOAD を設定すると、エフェクト パラメータは更新されるが、デバイスにダウンロードはされない。

DIEP_START フラグを設定すると、エフェクト パラメータは更新され、デバイスにダウンロードされる。そして、DirectInputEffect.Start メソッドが iterations パラメータに 1 を設定し、フラグなしで呼び出された場合とまったく同じように、エフェクトが始動する。DIEP_START で更新処理を付加した方法の方が Start メソッドを呼び出す方法よりも少し高速である。これは前者の方法では、デバイスに送信する情報が少なくて済むためである。

DIEP_NODOWNLOAD と DIEP_START のどちらも設定されず、エフェクトを再生していないときは、パラメータは更新され、デバイスにダウンロードされる。

DIEP_NODOWNLOAD と DIEP_START のどちらも設定されず、エフェクトが再生中のときは、デバイスが実行中 (オンザフライ) 更新をサポートしていれば、パラメータは更新される。上記以外の場合、処理は DIEP_NORESTART フラグの状態に左右される。このフラグが設定されていれば、エラー コード DIERR_EFFECTPLAYING が返される。このフラグがなければ、エフェクトは停止し、パラメータが更新され、エフェクトが再開する。


DirectInputEffect.Start

エフェクトの再生を開始する。エフェクトが既に再生中ならば、最初から開始される。エフェクトがダウンロードされていないか、または前回のダウンロード以来、変更されている場合は、開始前にエフェクトがダウンロードされる。この処理はデフォルトで行われる。これを抑制するには、DIES_NODOWNLOAD フラグを渡せばよい。

object.Start(iterations As Long, flags As Long)

指定項目

object
DirectInputEffect オブジェクトを指定する。
iterations
連続してエフェクトを再生する回数。エンベロープは、補間ごとに再調整される。

エフェクトを一度だけ再生するには、1 を渡す。明示的に停止されるまで反復再生するには、-1 を渡す。エンベロープを再調整しないで、明示的に停止されるまでエフェクトを再生するには、DirectInputEffect.SetParameters メソッドを使用してエフェクト パラメータを修正し、DIEFFECT の lDuration メンバを -1 に変更する。

flags
デバイスがエフェクトをどのように再生するかを表す、CONST_DIESFLAGS 列挙のフラグ。ゼロ、または 1 つ以上のフラグを取ることができる。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかのエラー コードが設定される。

DIERR_INVALIDPARAM
DIERR_INCOMPLETEEFFECT
DIERR_NOTEXCLUSIVEACQUIRED
DIERR_NOTINITIALIZED
DIERR_UNSUPPORTED

注意

このメソッドを成功させるには、デバイスを排他協調レベルで取得しなければならない。

複数回の補間をサポートしないデバイスもある。


DirectInputEffect.Stop

エフェクトの再生を停止する。

object.Stop()

指定項目

object
DirectInputEffect オブジェクトを指定する。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかのエラー コードが設定される。

DIERR_NOTEXCLUSIVEACQUIRED
DIERR_NOTINITIALIZED

注意

このメソッドを成功させるには、デバイスを排他協調レベルで取得しなければならない。


DirectInputEffect.Unload

デバイスからエフェクトを削除する。エフェクトが再生されている場合、エフェクトは、アンロードされる前に自動的に停止する。

object.Unload()

指定項目

object
DirectInputEffect オブジェクトを指定する。

エラー コード

失敗すればエラーが発生し、Err.Number に次のいずれかのエラー コードが設定される。

DIERR_INPUTLOST
DIERR_INVALIDPARAM
DIERR_NOTEXCLUSIVEACQUIRED
DIERR_NOTINITIALIZED

注意

このメソッドを成功させるには、デバイスを排他協調レベルで取得しなければならない。


DirectInputEnumDeviceObjects

Microsoft® DirectInputEnumDeviceObjects クラスは、システムにインストールされている DirectInputDevice8 オブジェクトを列挙する。このオブジェクトは、DirectInputDevice8.GetDeviceObjectsEnum メソッドを呼び出した結果として作成され、データが格納される。

このクラスには、次のメソッドがある。

情報 | GetCount
 | GetItem


DirectInputEnumDeviceObjects.GetCount

DirectInputEnumDeviceObjects コレクション内の項目数が返される。

object.GetCount() As Long

指定項目

object
DirectInputEnumDeviceObjects オブジェクトを指定する。

戻り値

デバイスに対して列挙されたデバイス オブジェクトの数が返される。

エラー コード

なし。


DirectInputEnumDeviceObjects.GetItem

指定デバイス オブジェクトを表すオブジェクトを取得する。

object.GetItem(index As Long) _
  As DirectInputDeviceObjectInstance

指定項目

object
DirectInputEnumDeviceObjects オブジェクトを指定する。
index
取得する列挙項目のインデックス。

戻り値

DirectInputDeviceObjectInstance オブジェクトが返される。このオブジェクトのメソッドを使って、デバイス オブジェクトに関する情報を取得する。

エラー コード

失敗した場合はエラーが発生し、Err.Number が設定される。

注意

DirectInputEnumDeviceObjects に含まれる項目数を取得するには、まず DirectInputEnumDeviceObjects.GetCount メソッドを呼び出す。

アプリケーションは、特定のキーボードのキーやインジケータ ランプが存在するかどうかの確認をこのメソッドに依存するべきではない。これらのオブジェクトは、存在しないにもかかわらず列挙される可能性がある。利用可能なオブジェクトの基本セットはデバイス サブタイプから決定できるものの、メニュー キーなどの追加オブジェクトが利用できるかどうかを確実に判断できる方法はない。


DirectInputEnumDevices8

DirectInputEnumDevices8 クラスは、システムにインストールされている Microsoft® DirectInput® デバイスを列挙する。このオブジェクトは、DirectInput8.GetDIDevices および DirectInput8.GetDevicesBySemantics メソッドを呼び出した結果として作成され、データが格納される。

このクラスには、次のメソッドがある。

GetCount
GetItem


DirectInputEnumDevices8.GetCount

DirectInputEnumDevices8 コレクション内の Microsoft® DirectInput® デバイスの数を取得する。

object.GetCount() As Long

指定項目

object
DirectInputEnumDevices8 オブジェクトを指定する。

戻り値

DirectInputEnumDevices8 コレクション内の DirectInput® デバイスの数が返される。

エラー コード

なし。


DirectInputEnumDevices8.GetItem

列挙されたデバイスに関する情報を取得する。

object.GetItem(index As Long) As DirectInputDeviceInstance8

指定項目

object
DirectInputEnumDevices8 オブジェクトを指定する。
index
DirectInputEnumDevices8 コレクション内のデバイスのインデックス。

戻り値

DirectInputDeviceInstance8 オブジェクトが返される。このオブジェクトのメソッドを使って、デバイスに関する情報を取得する。

エラー コード

失敗した場合はエラーが発生し、Err.Number が設定される。

注意

DirectInputEnumDevices8 に含まれる項目数を取得するには、まず DirectInputEnumDevices8.GetCount メソッドを呼び出す。


DirectInputEnumEffects

DirectInputEnumEffects クラスのオブジェクトは、デバイスでサポートされるフォース フィードバック エフェクトのコレクションを表し、エフェクトに関する情報の取得に使用される。オブジェクトを作成するには、DirectInputDevice8.GetEffectsEnum メソッドを使用する。

このクラスには、次のメソッドがある。

情報 | GetCount
 | GetDynamicParams
 | GetEffectGuid
 | GetName
 | GetStaticParams
 | GetType


DirectInputEnumEffects.GetCount

コレクション内で列挙されたエフェクト数を取得する。

object.GetCount() As Long

指定項目

object
DirectInputEnumEffects オブジェクトを指定する。

戻り値

コレクション内の項目数が返される。

エラー コード

失敗した場合はエラーが発生し、Err.Number が設定される。


DirectInputEnumEffects.GetDynamicParams

エフェクトを停止せずに DirectInputEffect.SetParameters メソッドで変更できるエフェクト パラメータについての情報を取得する。

object.GetDynamicParams(i As Long) As CONST_DIEPFLAGS

指定項目

object
DirectInputEnumEffects オブジェクトを指定する。
i
コレクション内のエフェクトのインデックス (1 が起点)。

戻り値

エフェクトの再生中に動的に更新可能なパラメータを表す CONST_DIEPFLAGS 列挙のフラグが返される。

エラー コード

失敗した場合はエラーが発生し、Err.Number が設定される。

参照

DirectInputEffect.SetParameters


DirectInputEnumEffects.GetEffectGuid

サポートされるエフェクトの GUID を取得する。この GUID は、DirectInputDevice8.CreateEffect メソッドに渡される。

object.GetEffectGuid(i As Long) As String

指定項目

object
DirectInputEnumEffects オブジェクトを指定する。
i
コレクション内のエフェクトのインデックス (1 が起点)。

戻り値

GUID が文字列形式で返される。標準のエフェクトの場合、戻り値は、"GUID_ConstantForce" などのエイリアスである。

エラー コード

失敗した場合はエラーが発生し、Err.Number が設定される。

参照

GUID の使い方


DirectInputEnumEffects.GetName

エフェクトの名前を取得する。

object.GetName(i As Long) As String

指定項目

object
DirectInputEnumEffects オブジェクトを指定する。
i
コレクション内のエフェクトのインデックス (1 が起点)。

戻り値

"Constant Force" など、エフェクトの名前が返される。

エラー コード

失敗した場合はエラーが発生し、Err.Number が設定される。


DirectInputEnumEffects.GetStaticParams

デバイスでサポートされるエフェクト パラメータに関する情報を取得する。

object.GetStaticParams(i As Long) As CONST_DIEPFLAGS

指定項目

object
DirectInputEnumEffects オブジェクトを指定する。
i
コレクション内のエフェクトのインデックス (1 が起点)。

戻り値

エフェクトがサポートするパラメータを表す CONST_DIEPFLAGS 列挙のフラグが返される。

エラー コード

失敗した場合はエラーが発生し、Err.Number が設定される。


DirectInputEnumEffects.GetType

エフェクトのタイプと能力に関する情報を取得する。

object.GetType(i As Long) As CONST_DIEFTFLAGS

指定項目

object
DirectInputEnumEffects オブジェクトを指定する。
i
コレクション内のエフェクトのインデックス (1 が起点)。

戻り値

エフェクトに関する情報を表す CONST_DIEFTFLAGS 列挙のフラグが返される。

エラー コード

失敗した場合はエラーが発生し、Err.Number が設定される。

注意

エフェクト タイプは下位バイトに格納され、&HFF と AND を取ることで、ビットごとに取得される。


型

ここでは、以下の Microsoft® DirectInput® 型を説明する。

  • DIACTION
  • DIACTIONFORMAT
  • DICOLORSET
  • DICONDITION
  • DICONFIGUREDEVICESPARAMS
  • DICONSTANTFORCE
  • DIDATAFORMAT
  • DIDEVCAPS
  • DIDEVICEIMAGEINFO
  • DIDEVICEIMAGEINFOHEADER
  • DIDEVICEOBJECTDATA
  • DIEFFECT
  • DIENVELOPE
  • DIJOYSTATE
  • DIJOYSTATE2
  • DIKEYBOARDSTATE
  • DIMOUSESTATE
  • DIMOUSESTATE2
  • DIOBJECTDATAFORMAT
  • DIPERIODICFORCE
  • DIPROPGUIDANDPATH
  • DIPROPLONG
  • DIPROPRANGE
  • DIPROPSTRING
  • DIRAMPFORCE


DIACTION

単一のアプリケーション アクションに対する、デバイス オブジェクトまたは仮想コントロールとのマッピングに関する情報を、指定および取得する。

Type DIACTION
    ActionName As String
    lAppData As Long
    lFlags As Long
    lHow As Long
    lObjId As Long
    lSemantic As Long
End Type

メンバ

ActionName
アクションのアプリケーション定義の名前。この文字列は、DirectInput8.ConfigureDevices が呼び出される際に、デバイス プロパティ シートで表示される。sResIDString が空の文字列でない場合、このメンバは無視される。
lAppData
アクションに関連付けられたコントロールの状態が変化するときに、アプリケーションに返される値。この値は、DirectInputDevice8.GetDeviceData が取得する DIDEVICEOBJECTDATA 型の lUserData メンバに返される。
lFlags
特定の属性または処理を要求するのに使用されるフラグ。ゼロ、または CONST_DIAFLAGS 列挙内の 1 つ以上の値を取ることができる。
lHow
アクションを構成するために Microsoft® DirectInput® で使用されるマッピングの仕組み。このメンバは、DirectInputDevice8.BuildActionMap から型が返されるときに、CONST_DIAHFLAGS 列挙中の 1 つのメンバを受け取る。

アクション マップが DirectInputDevice8.SetActionMap に渡されるときに、このメンバは無視される。

lObjId
コントロール識別子。
lSemantic
ジョイスティックの場合、仮想コントロールを表す、このアプリケーション ジャンルの定義済みアクション マッピング定数。「CONST_DIGENRE」を参照すること。

この値に CONST_DIMAPFLAGS 列挙の 1 つを使って、ジャンルに定義されていない仮想コントロールにアクションをマップすることもできる。

キーボード、マウス、または Microsoft DirectPlay® 音声デバイスの場合、特定のデバイス オブジェクトを表す定数。

参照

CONST_DIKEYBOARDFLAGS、CONST_DIMOUSEFLAGS、CONST_DIVOICEFLAGS


DIACTIONFORMAT

アクション マップに関する情報を指定および取得する。

Type DIACTIONFORMAT
    ActionArray() As DIACTION
    ActionMapName As String
    guidActionMap As String
    lActionCount As Long
    lAxisMax As Long
    lAxisMin As Long
    lBufferSize As Long
    lDataSize As Long
    lGenre As Long
End Type

メンバ

ActionArray
DIACTION 型から成る配列。それぞれの型が、アクションと仮想コントロールまたはデバイス オブジェクトのマップ方法、およびマッピング情報のユーザーに対する表示方法を表す。
ActionMapName
アクション マップの登録名。
guidActionMap
アクション マップを識別する GUID。デバイス メーカーはこの値を使って特定のタイトルのマッピングを調整できる。
lActionCount
ActionArray 内の要素数。
lAxisMax
すべての軸で取得される計測データの範囲の最大値。アクションに対して DIACTION 型に DIA_NORANGE フラグが設定された場合、この値は特定のアクション軸に対して無視される。「注意」を参照すること。
lAxisMin
すべての軸で取得される計測データの範囲の最小値。アクションに対して DIACTION 型に DIA_NORANGE フラグが設定された場合、この値は特定のアクション軸に対して無視される。「注意」を参照すること。
lBufferSize
アクション マップが適用される各デバイスのバッファ内の入力データ パケット数を指定する値。「注意」を参照すること。
lDataSize
直接デバイス データを使用するデバイスが返すデバイス データのサイズをバイト単位で指定する値。この型が DirectInputDevice8.SetActionMap に渡されるときに、この値は、メソッドに渡される DIACTION 型の配列に含まれる要素数を 4 倍した値となる。
lGenre
アプリケーションのジャンル。名前の先頭に「DIVIRTUAL」が付く、CONST_DIGENRE 列挙のメンバのいずれか。

注意

lAxisMax および lAxisMin メンバは、軸アクションに対してのみ有効であり、ほかのすべてのアクションではゼロを設定する必要がある。この型を DirectInputDevice8.SetActionMap に渡す前にこれらのメンバを設定することは、DIPROPRANGE 型を DirectInputDevice8.SetProperty に渡して範囲プロパティを設定することと同じ意味を持つ。

DirectInputDevice8.GetDeviceData を使ってデータを取得する場合は、バッファ サイズをゼロより大きい値に設定する必要がある。アプリケーションが、この型を DirectInputDevice8.SetActionMap に渡す前に、必要なバッファ サイズを lBufferSize メンバに設定する場合、DirectInputDevice8.SetProperty で DIPROP_BUFFERSIZE プロパティを設定する必要はない。


DICOLORSET

デバイス構成ユーザー インターフェイスを描画する配色を表す。これは DICONFIGUREDEVICESPARAMS 型の一部である。

Type DICOLORSET
    cAreaFill As Long
    cBorder As Long
    cCalloutHighlight As Long
    cCalloutLine As Long
    cControlFill As Long
    cHighlightFill As Long
    cTextFore As Long
    cTextHighlight As Long
End Type

メンバ

cAreaFill
タブやボタンなどのコントロールの外側の塗りつぶしの色。
cBorder
枠線の色。タブやボタンなどのコントロールを囲む線を表示するために使用される。
cCalloutHighlight
コールアウト線の表示に使用される色。
cCalloutLine
コールアウト線の表示に使用される色。
cControlFill
タブやボタンなどのコントロールの塗りつぶしの色。
cHighlightFill
強調表示テキストの塗りつぶしの色。
cTextFore
テキストの前景色。
cTextHighlight
強調表示テキストの前景色。

注意

テキストの背景色は常に透明である。


DICONDITION

DIEFFECT 型に含まれるフォース フィードバック条件のパラメータを表す。

Type DICONDITION
    lDeadBand As Long
    lNegativeCoefficient As Long
    lNegativeSaturation As Long
    lOffset As Long
    lPositiveCoefficient As Long
    lPositiveSaturation As Long
End Type

メンバ

lDeadBand
0 ～ 10,000 の範囲にある、条件がアクティブでない lOffset 周辺の領域。つまり、lOffset - lDeadBand と lOffset + lDeadBand の間では、条件はアクティブではない。
lNegativeCoefficient
-10,000 ～ +10.000 の範囲にある、オフセットの負側の係数定数。

デバイスが正と負に分かれた係数をサポートしていない場合、lNegativeCoefficient 値は無視され、lPositiveCoefficient 値が正負両方の係数として使用される。

lNegativeSaturation
0 ～ 10,000 の範囲にある、オフセットの負側の最大フォース出力。

デバイスがフォースの飽和値をサポートしない場合、このメンバ値は無視される。

デバイスが正と負に分かれた飽和値をサポートしていない場合、lNegativeSaturation 値は無視され、lPositiveSaturation 値が正負両方の飽和値として使用される。

lOffset
-10,000 ～ +10.000 の範囲にある、条件のオフセット。
lPositiveCoefficient
-10,000 ～ +10.000 の範囲にある、オフセットの正側の係数定数。
lPositiveSaturation
0 ～ 10,000 の範囲にある、オフセットの正側の最大フォース出力。

デバイスがフォースの飽和をサポートしない場合、このメンバ値は無視される。

注意

条件のタイプが異なれば、パラメータの意味も異なるが、基本的な考え方は、条件に起因するフォースは、A(q - q0) に等しくなるということである。ここで、A は、スケーリング係数、q はある距離であり、q0 は、その距離に対する中立値である。

上記の単純な式は、デッドバンドにゼロ以外の値が指定された場合は調整しなければならない。距離が lOffset - lDeadBand より小さければ、生成されるフォースは、次の式で示される。

force = lNegativeCoefficient * (q - (lOffset - lDeadBand))

同様に、距離が lOffset + lDeadBand より大きければ、生成されるフォースは、次の式で示される。

force = lPositiveCoefficient * (q - (lOffset + lDeadBand))

スプリング条件は、軸の位置を距離として使用する。

ダンパ条件は、軸の速度を距離として使用する。

慣性条件は、軸の加速度を距離として使用する。


DICONFIGUREDEVICESPARAMS

デバイス構成プロパティ シートに関する情報を格納する。DirectInput8.ConfigureDevices メソッドで使用される。

Type DICONFIGUREDEVICESPARAMS
    ActionFormats() As DIACTIONFORMAT
    DDSTarget As Unknown
    dics As DICOLORSET
    FormatCount As Long
    hwnd As Long
    UserCount As Long
    UserNames() As String
End Type

メンバ

ActionFormats
DIACTIONFORMAT 型の配列。ゲームで使用される各ジャンルのアクション マッピング情報を格納する。入力時、この配列にはアクションとコントロールのマッピング、および各マッピングのコールアウトとして表示する文字列が格納される。構成インターフェイスでは、配列内と同じ順序でドロップダウン リストにジャンルが表示される。
DDSTarget
構成ユーザー インターフェイスの Direct3DSurface8 オブジェクト。デバイス イメージは、ターゲット サーフェスの背景サーフェスに対してアルファブレンドされる。

DirectDraw を使用しないアプリケーションと、DirectDraw を使用するが、全画面を使用するのではなくウィンドウ化して実行されるアプリケーションは、このパラメータに NULL を渡すことができる。その場合、Microsoft DirectInput® は Windows GDI (Graphics Device Interface) 関数を使用して構成ユーザー インターフェイス イメージを描画する。

dics
構成ユーザー インターフェイスに適用する配色を表す DICOLORSET 型。
FormatCount
ActionFormats 配列中の要素の数。
hwnd
呼び出し元アプリケーションの最上位ウィンドウのハンドル。このメンバが必要なのは、アプリケーションがウィンドウ表示モードで稼働している場合のみであり、それ以外は無視される。
UserCount
UserNames 配列中の要素の数。ゼロは無効な値である。UserCount 値が、UserNames() が指す配列に実際に含まれるエントリの数より大きい場合、メソッドは失敗し、DIERR_INVALIDPARAM を返す。UserNames 配列が NULL に設定されている場合、UserCount 内の値は無視される。
UserNames
ユーザー名の配列。このパラメータを NULL に設定すると、UserCount で決定される数のデフォルト名を要求できる。アプリケーションが UserCount より多い名前を渡す場合、指定数内の名前だけが使用される。アプリケーションが現在デバイスに割り当てられた名前とは異なる名前を指定する場合、すべてのデバイスで所有権が取り消され、一致しない名前用にデフォルト名が作成され、すべてのデバイスでインターフェイスに "(No User)" が表示される。


DICONSTANTFORCE

DIEFFECT 型に含まれるコンスタント フォースのパラメータを表す。

Type DICONSTANTFORCE
    lMagnitude As Long
End Type

メンバ

lMagnitude
-10.000 ～ +10.000 の範囲にある、エフェクトのマグニチュード。エンベロープがこのエフェクトに適用されていれば、この値は、維持期間のマグニチュードを表す。エンベロープの適用がなければ、この値は、エフェクト全体の振幅を表す。


DIDATAFORMAT

デバイスのデータ形式を表す。この型は、DirectInputDevice8.SetDataFormat メソッドで使用される。

Type DIDATAFORMAT
    dataSize As Long
    lFlags As CONST_DIDATAFORMATFLAGS
    lObjSize As Long
    numObjs As Long
End Type

メンバ

dataSize
デバイスが返すデータ パケットのバイト単位のサイズ。この値は、4 の倍数であり、かつデータ パケット内のオブジェクト データの最大オフセット値より大きくなければならない。
lFlags
データ形式のほかの属性を表すフラグ。この値は、CONST_DIDATAFORMATFLAGS 列挙のいずれかを取ることができる。
lObjSize
DIOBJECTDATAFORMAT 型のバイト単位のサイズ。
numObjs
返されるデータのオブジェクト数。

注意

アプリケーションが DIDATAFORMAT 型を作成する必要があるのは、標準以外のデバイスを使用する場合のみである。マウス、キーボード、およびジョイスティックの場合は、DirectInputDevice8.SetCommonDataFormat でデータ形式を設定する。


DIDEVCAPS

Microsoft® DirectInput® デバイスの機能を表す。この型は、DirectInputDevice8.GetCapabilities メソッドで使用される。

Type DIDEVCAPS
    lAxes As Long
    lButtons As Long
    lDevType As Long
    lDriverVersion As Long
    lFFMinTimeResolution As Long
    lFFSamplePeriod As Long
    lFirmwareRevision As Long
    lFlags As CONST_DIDEVCAPSFLAGS
    lHardwareRevision As Long
    lPOVs As Long
End Type

メンバ

lAxes
デバイス上で使用可能な軸の数。
lButtons
デバイス上で使用可能なボタンの数。
lDevType
デバイスのタイプとサブタイプに関する情報を格納したパック値。DirectInputDeviceInstance8.GetDevType メソッドが返すのと等しい値である。
lDriverVersion
デバイス ドライバのバージョン番号。
lFFMinTimeResolution
フォース フィードバック エフェクトの再生時にデバイスが分解可能な最小時間 (マイクロ秒単位)。デバイスは、すべての時間を最も近い増加値に丸める。たとえば、lFFMinTimeResolution の値が 1000 の場合には、デバイスはすべての時間を最も近いミリ秒に丸める。
lFFSamplePeriod
未加工のフォース コマンドを連続して再生する際の、再生間隔の最小時間。
lFirmwareRevision
デバイスのファームウェア リビジョン番号。
lFlags
デバイスに関連付けられたフラグ。CONST_DIDEVCAPSFLAGS 列挙の定数を組み合わせた値となる。
lHardwareRevision
デバイスのハードウェア リビジョン番号。
lPOVs
デバイス上で使用可能な視点コントローラの数。

注意

バージョン番号の付け方はデバイス メーカーによって異なる。確実なのは、新しいバージョンには以前のバージョンよりも大きい数字が付く、ということだけである。


DIDEVICEIMAGEINFO

デバイス イメージを表示する、またはイメージにコールアウトをオーバーレイするのに必要な情報を格納する。この型は DIDEVICEIMAGEINFOHEADER 型内の配列として、DirectInputDevice8.GetImageInfo メソッドに渡される。

Type DIDEVICEIMAGEINFO
    CalloutLine(0 To 4) As POINT
    CalloutRect As RECT
    flags As Long
    ImagePath As String
    ObjId As Long
    ViewID As Long
    OverlayRect As RECT
    TextAlign As Long
    ValidPts As Long
End Type

メンバ

CalloutLine
コールアウトの線を描画するポイントの座標を指定する型の配列。コールアウト線は、デバイス コントロールと、ゲーム アクションのキャプションを結ぶ線である。各線は、1 ～ 4 のセグメントを持つことができる。このメンバは、flags に DIDIFT_OVERLAY フラグが含まれる場合にのみ有効である。
CalloutRect
ゲーム アクションの文字列が表示される長方形の座標を指定する型。アプリケーションはクリッピングを処理する。このメンバは、flags に DIDIFT_OVERLAY フラグが含まれる場合にのみ有効である。
flags
イメージの使用目的を記述したフラグ。このメンバは、CONST_DIDIFTFLAGS 列挙のいずれか 1 つの値を使用できる。
DIDIFT_CONFIGURATION
ファイルは、デバイスに対するアクションの現在構成を表示するために使用される。オーバーレイ イメージの座標は、構成イメージの左上隅を起点とする相対座標である。
DIDIFT_OVERLAY
もし提供されていれば、ファイルは、構成イメージ上の特定のコントロールのオーバーレイである。ViewID、OverlayRect、ObjID、CalloutLine、CalloutRect、および TextAlign の各メンバは有効であり、これらに格納されたデータを使って、デバイスの単一コントロールのオーバーレイとコールアウト情報が表示される。ファイルが指定されない場合 (パス文字列が NULL)、rdOverlay 以外の関連するその他すべてのメンバが使用される。
ImagePath
デバイスのイメージを含むファイルの完全修飾パス。
ObjId
このデバイスのオーバーレイ イメージが対応するコントロール識別子。オブジェクト タイプ フラグとインスタンス値の組み合わせである。この識別子の詳細については、「DirectInputDeviceObjectInstance.GetType」を参照すること。このメンバは、flags に DIDIFT_OVERLAY フラグが含まれる場合にのみ有効である。
OverlayOffset
このオーバーレイを表示するデバイス構成イメージのオフセット。このメンバは、flags に DIDIFT_OVERLAY フラグが含まれる場合にのみ有効である。
OverlayRect
デバイス構成イメージの左上ピクセルを原点とする相対座標を使って、オーバーレイ イメージをペイントする対象の長方形。このメンバは、flags に DIDIFT_OVERLAY フラグが含まれる場合にのみ有効である。
TextAlign
CalloutRect メンバが表す四角形内のテキストの配置を指定する値。CONST_DIDALFLAGS 列挙からの、1 つの水平方向の配置フラグと、1 つの垂直方向の配置フラグの組み合わせでなければならない。

定義済みの水平方向配置フラグは次のとおり。

DIDAL_LEFTALIGNED
テキストを左枠線に揃える。
DIDAL_CENTERED
テキストを水平方向の中央に寄せる。
DIDAL_RIGHTALIGNED
テキストを右枠線に揃える。

定義済みの垂直方向配置フラグは次のとおり。

DIDAL_MIDDLE
テキストを垂直方向の中央に寄せる。
DIDAL_TOPALIGNED
テキストを上枠線に揃える。
DIDAL_BOTTOMALIGNED
テキストを下枠線に揃える。

このメンバは、flags に DIDIFT_OVERLAY フラグが含まれる場合にのみ有効である。

ValidPts
CalloutLine 配列中の要素の数。
ViewID
デバイス ビュー イメージ (DIDIFT_CONFIGURATION) の場合、これはデバイス ビューの ID である。デバイス コントロール オーバーレイ (DIDIFT_OVERLAY) の場合、この値はデバイス ビューを ID によって参照する。デバイス ビューによって、イメージとコールアウト情報が表示される。


DIDEVICEIMAGEINFOHEADER

デバイス イメージに関する情報を格納する。この型は、 DirectInputDevice8.GetImageInfo メソッドに渡される。リターン時に、デバイスに関する情報と、デバイス構成プロパティ シートでデバイスを表すイメージに関する情報が格納される。

Type DIDEVICEIMAGEINFOHEADER
    Axes As Long
    Buttons As Long
    ImageCount As Long
    Images() As DIDEVICEIMAGEINFO
    POVs As Long
    Views As Long
End Type

メンバ

Axes
デバイス上の軸の数。
Buttons
デバイス上のボタンの数。
ImageCount
Images 配列中の要素の数。
Images
デバイス イメージとビュー、オーバーレイ イメージ、およびコールアウト文字列の座標を表す DIDEVICEIMAGEINFO 型の配列。
POVs
デバイス上の視点コントローラの数。
Views
このデバイスのビューの数。

注意

この型を DirectInputDevice8.GetImageInfo に渡す前に、アプリケーションは、次のように ImageCount メンバと Images メンバを初期化しなければならない。

' didev は DirectInputDevice8 オブジェクトであると仮定する。

Dim count as Integer
Dim diImageInfoHdr

count = didev.GetImageInfoCount
With diImageInfoHdr
  ImageCount = count
  ReDim Images(count)
End With

型のメンバのうち ImageCount 以外は、メソッド呼び出しによりデータが設定される。

参照

DirectInputDevice8.GetImageInfoCount


DIDEVICEOBJECTDATA

バッファリング デバイスの未加工の情報を格納する。この型は、DirectInputDevice8.GetDeviceData メソッドで使用される。

Type DIDEVICEOBJECTDATA
    lData As Long
    lOfs As Long
    lSequence As Long
    lTimeStamp As Long
    lUserData As Long
End Type

メンバ

lData
デバイスから取得されるデータ。

軸からの入力の場合、デバイスが相対軸モードにあれば、相対軸の動きが報告される。デバイスが絶対軸モードにあれば、絶対座標が報告される。

ボタンからの入力の場合、lData の下位バイトだけが有意である。下位バイトの上位ビットは、ボタンがダウン状態の場合に設定され、アップ状態の場合に消去される。

lOfs
報告されているデータが属するオブジェクトの現在のデータ形式に対するオフセット。つまり、DirectInputDevice8.GetDeviceStateX メソッド (GetDeviceStateMouse など、X は特定のデバイスを指す) を呼び出してデータを取得した場合に、データが格納されている場所。デバイスがキーボードとしてアクセスされる場合、この値を CONST_DIKEYFLAGS 列挙のメンバと比較することで、どのキーがイベントを生成したかを判定できる。マウスやジョイスティックの場合、lOfs の値は、DIMOUSESTATE、DIJOYSTATE、または DIJOYSTATE2 型 (DirectInputDevice8.SetCommonDataFormat で設定されたデータ形式により異なる) に含まれる軸またはボタンのバイト オフセットと等しい。これらのオフセットの定数は、CONST_DIMOUSEOFS 列挙および CONST_DIJOYSTICKOFS 列挙に含まれる。DirectInputDevice8.SetDataFormat でカスタム データ形式が設定されていた場合、lOfs は、カスタム データ形式内のデバイス オブジェクトの場所のオフセットである。
lSequence
このイベントに対する Microsoft® DirectInput® シーケンス番号。すべての入力イベントには、昇順のシーケンス番号が割り当てられている。これにより、異なるデバイスからのイベントを時間順にソートすることが可能になる。この値は、循環して初期値に戻るので、2 つのシーケンス番号を比較する場合には注意しなければならない。
lTimeStamp
入力イベントが生成されたミリ秒単位のシステム時間。この値は、約 50 日で循環する。
lUserData
前回の DirectInputDevice8.SetActionMap の呼び出しで、このオブジェクトに割り当てられたアプリケーション定義のアクション値。これは、オブジェクトに関連付けられた DIACTION 型の lAppData メンバの値である。アクション マッピングを使用していない場合はこの値を無視する。

型構造体が SendDeviceData メソッドと共に使用される場合、このメンバは必ずゼロになる。


DIEFFECT

フォース フィードバック エフェクトを表す。この型は、エフェクトのパラメータを設定するために DirectInputDevice8.CreateEffect メソッドや DirectInputEffect.SetParameters メソッドに渡される。この型に含まれる既存のパラメータは、DirectInputEffect.GetParameters メソッドで取得される。

Type DIEFFECT
    bUseEnvelope As Long
    conditionFlags As CONST_DICONDITIONFLAGS
    conditionX As DICONDITION
    conditionY As DICONDITION
    constantForce As DICONSTANTFORCE
    envelope As DIENVELOPE
    lDuration As Long
    lFlags As Long
    lGain As Long
    lSamplePeriod As Long
    lStartDelay As Long
    lTriggerButton As Long
    lTriggerRepeatInterval As Long
    periodicForce As DIPERIODICFORCE
    rampForce As DIRAMPFORCE
    x As Long
    y As Long
End Type

メンバ

bUseEnvelope
envelope メンバに記述されるエンベロープがエフェクトに適用される場合は TRUE。
conditionFlags
conditionX メンバおよび conditionY メンバの使用を決定する CONST_DICONDITIONFLAGS 列挙のフラグ。
conditionX
x 軸の条件のパラメータを表す DICONDITION 型。別の型のエフェクトでは無視される。
conditionY
y 軸の条件のパラメータを表す DICONDITION 型。別の型のエフェクトでは無視される。
constantForce
コンスタント フォースのパラメータを表す DICONSTANTFORCE 型。別の型のエフェクトでは無視される。
envelope
エフェクトに適用されるエンベロープのパラメータを表す DIENVELOPE 型。bUseEnvelope メンバが TRUE の場合にのみ有効。
lDuration
マイクロ秒単位のエフェクトの継続時間。-1 という値は、無限の継続時間を表す。無限の継続時間を持つエフェクトにエンベロープが適用されていれば、アタックも適用され、無限の維持期間も適用されることになる。
lFlags
ゼロ、またはほかのメンバの解釈方法を指定する CONST_DIEFFFLAGS 列挙のメンバ。
lGain
エフェクトに適用されるゲイン。0 ～ 10,000 の範囲にある。ゲインとは、エフェクトの全マグニチュードとそのエンベロープに適用されるスケーリング係数である。
lSamplePeriod
デバイスがエフェクトをサンプリングする期間 (マイクロ秒単位)。つまり、フォースにおける変化の細分度。この値がゼロであれば、デフォルトの再生サンプリング速度を使用することを意味する。

デバイスが指定の速度でエフェクトをサンプリングできなければ、指定された値に最も近い速度を選択する。

カスタム サンプリング期間の設定は、特殊効果に使用できる。たとえば、サイン波を意図的に大きなサンプリングレートで再生すると、ざらざらした質感をもたらす。

lStartDelay
DirectInputEffect.Start を呼び出してからエフェクトを再生するまでに、デバイスが待機する時間 (マイクロ秒単位)。この値がゼロであれば、エフェクトの再生は直ちに開始される。
lTriggerButton
エフェクトをトリガするボタンのオフセット値。CONST_DIJOYSTICKOFS 列挙のメンバのいずれか 1 つの値を取る。エフェクトがトリガ ボタンを持たないことを示すには、-1 にする。
lTriggerRepeatInterval
ボタンの押下および押し続けによってエフェクトがトリガされたときの、1 回の再生の終了と開始の間隔を表す、マイクロ秒単位の時間。繰り返しを抑制するには、この値を -1 に設定する。

トリガの繰り返しをサポートしないデバイスもある。

periodicForce
周期的エフェクトのパラメータを表す DIPERIODICFORCE 型。別の型のエフェクトでは無視される。
rampForce
傾斜フォースのパラメータを表す DIRAMPFORCE 型。別の型のエフェクトでは無視される。
x
エフェクトの方向。多くの場合、方向は北 (通常、y 軸の負側) からの回転量として 1/100 度単位で表される。したがって、ゼロという値は、ユーザーの正面からくるフォースを示し、9000 という値は、ユーザーの右側からくるフォースを示す。以下同様に解釈する。この場合、y はゼロである。

lFlags に DIEFF_CARTESIAN が含まれている場合、これは x 軸上の相対フォース量を表すデカルト座標の値である。たとえば、x = -1 かつ y = 1 である場合、フォースは、南東方向からくる。詳細については、「エフェクトの方向」を参照すること。

y
lFlags に DIEFF_CARTESIAN が含まれている場合、これは ｙ 軸上の相対フォース量を表すデカルト座標の値である。それ以外の場合、ゼロでなければならない。


DIENVELOPE

DIEFFECT 型に含まれるエンベロープのパラメータを表す。

Type DIENVELOPE
    lAttackLevel As Long
    lAttackTime As Long
    lFadeLevel As Long
    lFadeTime As Long
End Type

メンバ

lAttackLevel
基線を基準とするエンベロープの始点における振幅。基線に対する相対値。0 ～ 10,000 の範囲である。エフェクトのタイプ固有データが、基線を指定していなければ、振幅はゼロを基準とする。
lAttackTime
維持期間レベルに到達するのに必要な、マイクロ秒単位の時間。
lFadeLevel
エンベロープの終点での振幅。基線に対する相対値。0 ～ 10,000 の範囲である。エフェクトのタイプ固有データが、基線を指定していなければ、振幅はゼロを基準とする。
lFadeTime
フェード レベルに到達するのに必要なマイクロ秒単位の時間。


DIJOYSTATE

ジョイスティック デバイスの状態を表す ("ジョイスティック" には、ゲーム パッドやステアリング ホイールなど、ほかのコントローラも含まれる)。この型は、DirectInputDevice8.GetDeviceStateJoystick メソッドで使用される。

Type DIJOYSTATE
    Buttons(0 To 31) As Byte
    POV(0 To 3) As Long
    rx As Long
    ry As Long
    rz As Long
    slider(0 To 1) As Long
    x As Long
    y As Long
    z As Long
End Type

メンバ

Buttons
ボタンの配列。バイトの高次ビットは、対応するボタンがダウン状態にあるときに設定され、ボタンがアップ状態または存在しないときには消去される。
POV
方向コントローラ (視点ハットなど)。この位置は、北から (ユーザーの正面側) 時計回りの実角度の 100 倍で表される。中心位置は通常 -1 と報告されるが、これについては「注意」を参照すること。5 つの位置しか持たないインジケータの場合、コントローラの値は -1、0、9,000、18,000、27,000 のいずれか 1 つの値を取る。
rx
x 軸回転。ジョイスティックにこの軸がなければ、値はゼロである。
ry
y 軸回転。ジョイスティックにこの軸がなければ、値はゼロである。
rz
z 軸の回転。ジョイスティックにこの軸がなければ、値はゼロである。
slider
2 つの追加軸。その意味はジョイスティックにより異なる。これらの値の意味についての情報を取得するには、DirectInputDevice8.GetObjectInfo メソッドを使用する。
x
x 軸。通常は、スティックの左右の動き。
y
y 軸。通常は、スティックの前後の動き。
z
z 軸。スロットル コントロールであることが多い。ジョイスティックにこの軸がなければ、値はゼロである。

注意

ジョイスティック型のアクセスをするには、DirectInputDevice8.SetCommonDataFormat メソッドを呼び出し、DIFORMAT_JOYSTICK 形式定数を渡すことで、デバイスの準備をしなければならない。

軸が相対モードである場合は、適切なメンバが位置の変化量を格納する。絶対モードの場合には、同じメンバが軸の絶対位置を格納する。

POV インジケータの中心位置を 65,535 と報告するドライバもある。POV インジケータが中心位置にあるかどうかは、次のようにして確認する。

Dim POVCentered as Boolean
POVCentered = MyDijoystate.POV(0) And &HFFFF

注 : Microsoft® DirectX® 7 では、一部のジョイスティックのスライダを Z 軸に割り当て、それ以降のコードでそのメンバからデータを取得することができた。DirectX 8 では、同じスライダをスライダ配列に割り当てる。アプリケーションを DirectX 8 に移植する場合は、この点を考慮する必要がある。スライダ配列からスライダ データを取得するために必要な変更があれば行うこと。

参照

DIJOYSTATE2


DIJOYSTATE2

拡張機能の付いたジョイスティック デバイスの状態を表す。この型は、DirectInputDevice8.GetDeviceStateJoystick2 メソッドで使用される。

この型は、フォース フィードバック デバイスなど、非常に特殊なコントローラ向けの型なので、通常、アプリケーションはこの型を使用する必要はない。標準のゲーム コントローラの場合、DirectInputDevice8.GetDeviceStateJoystick を呼び出すことで、DIJOYSTATE 型を使用してデータを取得する。

Type DIJOYSTATE2
    arx As Long
    ary As Long
    arz As Long
    aslider (0 to 1) As Long
    ax As Long
    ay As Long
    az As Long
    Buttons(0 To 127) As Byte
    frx As Long
    fry As Long
    frz As Long
    fslider(0 To 1) As Long
    fx As Long
    fy As Long
    fz As Long
    POV(0 To 3) As Long
    rx As Long
    ry As Long
    rz As Long
    slider(0 To 1) As Long
    vrx As Long
    vry As Long
    vrz As Long
    vslider(0 To 1) As Long
    vx As Long
    vy As Long
    vz As Long
    x As Long
    y As Long
    z As Long
End Type

メンバ

arx
x 軸の角加速度。
ary
y 軸の角加速度。
arz
z 軸の角加速度。
aslider
追加軸の加速度。
ax
x 軸の加速度。
ay
y 軸の加速度。
az
z 軸の加速度。
Buttons
ボタンの配列。バイトの高次ビットは、対応するボタンがダウン状態にあるときに設定され、ボタンがアップ状態または存在しないときには消去される。
frx
x 軸のトルク。
fry
y 軸のトルク。
frz
z 軸のトルク。
fslider
追加軸のフォース。
fx
x 軸のフォース。
fy
y 軸のフォース。
fz
z 軸のフォース。
POV
方向コントローラ (視点ハットなど) の配列。この位置は、北から (ユーザーの正面側) 時計回りの実角度の 100 倍で表される。中心位置は通常 -1 と報告されるが、これについては「注意」を参照すること。5 つの位置しか持たないインジケータの場合、コントローラの値は -1、0、9,000、18,000、27,000 のいずれか 1 つの値を取る。
rx
x 軸回転。ジョイスティックにこの軸がなければ、値はゼロである。
ry
y 軸回転。ジョイスティックにこの軸がなければ、値はゼロである。
rz
z 軸の回転 (方向舵に使用されることが多い)。ジョイスティックにこの軸がなければ、値はゼロである。
slider
2 つの追加軸。その意味はジョイスティックにより異なる。これらの値の意味についての情報を取得するには、DirectInputDevice8.GetObjectInfo メソッドを使用する。
vrx
x 軸の角速度。
vry
y 軸の角速度。
vrz
z 軸の角速度。
vslider
追加軸の速度の配列。
vx
x 軸の速度。
vy
y 軸の速度。
vz
z 軸の速度。
x
ジョイスティックの x 軸の情報 (通常は、スティックの左右の動き)。
y
ジョイスティックの y 軸の情報 (通常は、スティックの前後の動き)。
z
ジョイスティックの z 軸の情報 (通常は、スロットル制御)。ジョイスティックにこの軸がなければ、値はゼロである。

注意

拡張機能付きのジョイスティックにアクセスするには、DirectInputDevice8.SetCommonDataFormat メソッドを呼び出し、DIFORMAT_JOYSTICK2 データ形式変数を渡すことで、デバイスの準備をしなければならない。

軸が相対モードである場合は、適切なメンバが位置の変化量を格納する。絶対モードの場合には、同じメンバが軸の絶対位置を格納する。

POV インジケータの中心位置を 65,535 と報告するドライバもある。POV インジケータが中心位置にあるかどうかは、次のようにして確認する。

Dim POVCentered as Boolean
POVCentered = MyDijoystate2.POV(0) And &HFFFF

注 : Microsoft® DirectX® 7 では、一部のジョイスティックのスライダを Z 軸に割り当て、それ以降のコードでそのメンバからデータを取得することができた。DirectX 8 では、同じスライダをスライダ配列に割り当てる。アプリケーションを DirectX 8 に移植する場合は、この点を考慮する必要がある。スライダ配列からスライダ データを取得するために必要な変更があれば行うこと。


DIKEYBOARDSTATE

キーボードのキーの状態を表す。この型は、DirectInputDevice8.GetDeviceStateKeyboard メソッドで使用される。

Type DIKEYBOARDSTATE
    key(0 To 255) As Byte
End Type

メンバ

key
ボタンの状態の配列。この配列には、CONST_DIKEYFLAGS 列挙のメンバでインデックスを作成できる。各キーの上位ビットは、キーがダウン状態で設定され、アップ状態または存在しない場合に消去される。

注意

次のコードは、Esc キーが押されているかどうかを確認する例である。

Dim keyState as DIKEYBOARDSTATE
' diDevice は有効な DirectInputDevice8 オブジェクトである。

Call diDevice.GetDeviceStateKeyboard(keyState)
If (keyState.key(DIK_ESCAPE) And &H80) Then
    ' キーは押下されている。
End If


DIMOUSESTATE

4 つまでのボタンを持つマウス デバイスの状態を表す。この型は、DirectInputDevice8.GetDeviceStateMouse メソッドで使用される。

Type DIMOUSESTATE
    Buttons(0 To 3) As Byte
    lX As Long
    lY As Long
    lZ As Long
End Type

メンバ

Buttons
ボタンの状態の配列。バイトの高次ビットは、対応するボタンがダウン状態にあるときに設定される。
lX
x 軸。
lY
y 軸。
lZ
通常はホイールを表す z 軸。マウスに z 軸がなければ、この値はゼロである。

注意

DirectInputDevice8.SetCommonDataFormat メソッドに DIFORMAT_MOUSE 定数を渡すことで準備していたデバイスからは、この型に直接データが返される。

軸が相対モードである場合は、適切なメンバが、このメソッドを前回に呼び出して以降の位置の変化量を格納する。軸が絶対モードである場合は、同じメンバが、任意の始点に対する相対的な動きの累積を格納する。したがって、絶対軸位置は、ほかの絶対軸位置と比較する場合を除いて無意味となる。

参照

DIMOUSESTATE2


DIMOUSESTATE2

8 つまでのボタンを持つマウス デバイスの状態を表す。この型は、DirectInputDevice8.GetDeviceStateMouse2 メソッドで使用される。

Type DIMOUSESTATE2
    Buttons(0 To 7) As Byte
    lX As Long
    lY As Long
    lZ As Long
End Type

メンバ

Buttons
ボタンの状態の配列。バイトの高次ビットは、対応するボタンがダウン状態にあるときに設定される。
lX
x 軸。
lY
y 軸。
lZ
通常はホイールを表す z 軸。マウスに z 軸がなければ、この値はゼロである。

注意

DirectInputDevice8.SetCommonDataFormat メソッドに DIFORMAT_MOUSE2 定数を渡すことで準備していたデバイスからは、この型に直接データが返される。

軸が相対モードである場合は、適切なメンバが、このメソッドを前回に呼び出して以降の位置の変化量を格納する。軸が絶対モードである場合は、同じメンバが、任意の始点に対する相対的な動きの累積を格納する。したがって、絶対軸位置は、ほかの絶対軸位置と比較する場合を除いて無意味となる。

参照

DIMOUSESTATE


DIOBJECTDATAFORMAT

DirectInputDevice8.SetDataFormat メソッドで使用するためのデバイス オブジェクトのデータ形式を表す。

Type DIOBJECTDATAFORMAT {
    lFlags As CONST_DIDEVICEOBJINSTANCEFLAGS
    lOfs As Long
    lType As CONST_DIDFTFLAGS
    strGuid As String
End Type

メンバ

lFlags
ゼロ、または次の CONST_DIDEVICEOBJINSTANCEFLAGS 列挙の値。
DIDOI_ASPECTACCEL
DirectInputDevice8.SetDataFormat で選択されたオブジェクトは、加速度情報を報告する。
DIDOI_ASPECTFORCE
DirectInputDevice8.SetDataFormat で選択されたオブジェクトは、フォース情報を報告する。
DIDOI_ASPECTPOSITION
DirectInputDevice8.SetDataFormat で選択されたオブジェクトは、位置情報を報告する。
DIDOI_ASPECTVELOCITY
DirectInputDevice8.SetDataFormat で選択されたオブジェクトは、速度情報を報告する。
lOfs
入力ソースのデータを格納するデータ パケット内のバイト オフセット。この値は、軸など、Long サイズのデータに合うように、4 の倍数でなければならない。ボタンの場合はバイト整列でも構わない。
lType
オブジェクトを表すデバイス タイプ。オブジェクト タイプ (軸、ボタンなど) を表す CONST_DIDFTFLAGS 列挙の値の組み合わせであり、中央の 16 ビットには、オブジェクト インスタンス番号が格納される。
strGuid
入力ソースのタイプに対する一意な識別子。空の文字列は、あらゆるタイプのオブジェクトが許容されることを示す。

次の文字列は、デバイス オブジェクトのタイプを識別するために、実際の GUID 文字列の代わりに使用できる。

GUID_XAxis
GUID_YAxis
GUID_ZAxis
GUID_RxAxis
GUID_RyAxis
GUID_RzAxis
GUID_Slider
GUID_Button
GUID_Key
GUID_POV


DIPERIODICFORCE

DIEFFECT 型に含まれる周期的フォースのパラメータを表す。

Type DIPERIODICFORCE
    lOffset As Long
    lMagnitude As Long
    lPeriod As Long
    lPhase As Long
End Type

メンバ

lOffset
エフェクトのオフセット。エフェクトが生成するフォースは、lOffset - lMagnitude から lOffset + lMagnitude の範囲になる。lOffset メンバの値は、エフェクトに適用されるすべてのエンベロープに対する基線にもなる。
lMagnitude
0 ～ 10.000 の範囲にある、エフェクトのマグニチュード。エンベロープがこのエフェクトに適用されていれば、この値は、維持期間のマグニチュードを表す。エンベロープの適用がなければ、この値は、エフェクト全体の振幅を表す。
lPeriod
マイクロ秒単位のエフェクトの周期。
lPhase
0 ～ 35,999 の範囲内にある周期的エフェクトの再生開始位置。「注意」を参照すること。

注意

デバイス ドライバは lPhase メンバのすべての値をサポートしているとは限らない。サポートされていない値は、直近のサポート値に丸められる。


DIPROPGUIDANDPATH

GUID とパスを表す値を持つプロパティを表す。DirectInputDevice8.GetProperty メソッドで使用される。

Type DIPROPGUIDANDPATH
    GUID As String
    lHow As Long
    lObj As Long
    Path As String
End Type

メンバ

GUID
GUID を受け取る文字列。
lHow
lObj パラメータの解釈方法を指定する値。この値は、CONST_DIPHFLAGS 列挙のメンバのいずれかを取ることができる。

プロパティがデバイス全体を表す場合、lHow は DIPH_DEVICE である。

lObj
アクセスするプロパティが属するオブジェクト。

lHow メンバが DIPH_BYID であれば、このメンバは、設定または取得されるプロパティを持つオブジェクトの識別子とする。この値は、DirectInputDeviceObjectInstance.GetType メソッドを使用してオブジェクトごとに取得できる。

lHow メンバが DIPH_ BYOFFSET であれば、このメンバは、設定または取得されるプロパティを持つオブジェクトのデータ形式オフセットとする。この値は、DirectInputDeviceObjectInstance.GetOfs メソッドで取得できる。

Path
パスを受け取る文字列。


DIPROPLONG

プロパティが単一の値を取る場合に、DirectInputDevice8.SetProperty メソッドや DirectInputDevice8.GetProperty メソッドで、入力デバイスに設定、または入力デバイスから取得するプロパティ情報を格納する。

Type DIPROPLONG
    lData As Long
    lHow As Long
    lObj As Long
End Type

メンバ

lData
設定または取得されるプロパティ固有の値。
lHow
lObj パラメータの解釈方法を指定する値。この値は、CONST_DIPHFLAGS 列挙のメンバのいずれかを取ることができる。

lObj が DIPROP_AXISMODE または DIPROP_BUFFERSIZE である場合、これらのプロパティは個別のオブジェクトには設定できないので、lHow は DIPH_DEVICE でなければならない。

lObj
アクセスするプロパティが属するオブジェクト。

lHow メンバが DIPH_BYID であれば、このメンバは、設定または取得されるプロパティを持つオブジェクトの識別子とする。この値は、DirectInputDeviceObjectInstance.GetType メソッドを使用してオブジェクトごとに取得できる。

lHow メンバが DIPH_ BYOFFSET であれば、このメンバは、設定または取得されるプロパティを持つオブジェクトのデータ形式オフセットとする。この値は、DirectInputDeviceObjectInstance.GetOfs メソッドで取得できる。

lHow が DIPH_DEVICE である場合、この値はゼロである。

注意

SetProperty メソッドに型が渡される前に、すべてのメンバを適切な値で初期化する必要がある。GetProperty メソッドに型が渡される前に、lData を除くすべてのメンバを適切な値で初期化する必要がある。

参照

DIPROPRANGE


DIPROPRANGE

プロパティが値の範囲である場合に、DirectInputDevice8.SetProperty メソッドや DirectInputDevice8.GetProperty メソッドで、入力デバイスに設定または取得されるプロパティ情報を格納する。

Type DIPROPRANGE
    lHow As Long
    lMax As Long
    lMin As Long
    lObj As Long
End Type

メンバ

lHow
lObj メンバの解釈方法を指定する値。この値は、CONST_DIPHFLAGS 列挙のメンバのいずれかを取ることができる。
lMax
範囲の上限。デバイスの範囲に制限がなければ、DirectInputDevice8.GetProperty メソッドが戻るとき、この値は DIPROPRANGE_NOMAX (CONST_DINPUT 列挙の値) となる。
lMin
範囲の下限。デバイスの範囲に制限がなければ、DirectInputDevice8.GetProperty メソッドが戻るとき、この値は DIPROPRANGE_NOMIN (CONST_DINPUT 列挙の値) となる。
lObj
アクセスするプロパティが属するオブジェクト。

lHow メンバが DIPH_BYID であれば、このメンバは、設定または取得されるプロパティを持つオブジェクトの識別子とする。この値は、DirectInputDeviceObjectInstance.GetType メソッドを使用してオブジェクトごとに取得できる。

lHow メンバが DIPH_ BYOFFSET であれば、このメンバは、設定または取得されるプロパティを持つオブジェクトのデータ形式オフセットとする。この値は、DirectInputDeviceObjectInstance.GetOfs メソッドで取得できる。

lHow が DIPH_DEVICE である場合、この値はゼロである。

参照

DIPROPLONG


DIPROPSTRING

文字列プロパティを表す。DirectInputDevice8.GetProperty および DirectInputDevice8.SetProperty メソッドで使用される。

Type DIPROPSTRING
    lHow As Long
    lObj As Long
    PropString As String
End Type

メンバ

lHow
lObj メンバの解釈方法。
lObj
取得または設定するプロパティが属するオブジェクトの識別子。
PropString
プロパティを指定または取得する文字列。


DIRAMPFORCE

DIEFFECT 型に含まれる傾斜フォースのパラメータを表す。

Type DIRAMPFORCE
    lRangeEnd As Long
    lRangeStart As Long
End Type

メンバ

lRangeEnd
-10,000 ～ +10.000 の範囲にある、エフェクトの終点のマグニチュード。
lRangeStart
-10,000 ～ +10.000 の範囲にある、エフェクトの始点のマグニチュード。

注意

傾斜フォース エフェクトの継続時間は有限でなければならない。


列挙

Microsoft® DirectInput® は、Microsoft Visual Basic® のステートメント補完機能を利用するために、列挙を使って定数をグループ化する。DirectInput で使用される列挙は次のとおりである。

  • CONST_DI8DEVICESUBTYPE
  • CONST_DI8DEVICETYPE
  • CONST_DIAFLAGS
  • CONST_DIAHFLAGS
  • CONST_DICDFLAGS
  • CONST_DICOMMONDATAFORMATS
  • CONST_DICONDITIONFLAGS
  • CONST_DIDALFLAGS
  • CONST_DIDATAFORMATFLAGS
  • CONST_DIDBAMFLAGS
  • CONST_DIDEVCAPSFLAGS
  • CONST_DIDEVICEOBJINSTANCEFLAGS
  • CONST_DIDFTFLAGS
  • CONST_DIDGDDFLAGS
  • CONST_DIDIFTFLAGS
  • CONST_DIDSAMFLAGS
  • CONST_DIEDBSFLFLAGS
  • CONST_DIEFFFLAGS
  • CONST_DIEFTFLAGS
  • CONST_DIEGESFLAGS
  • CONST_DIENUMDEVICESFLAGS
  • CONST_DIEPFLAGS
  • CONST_DIESFLAGS
  • CONST_DIFEFFLAGS
  • CONST_DIGENRE
  • CONST_DIGFFSFLAGS
  • CONST_DIJOYSTICKOFS
  • CONST_DIKEYBOARDFLAGS
  • CONST_DIKEYFLAGS
  • CONST_DIMAPFLAGS
  • CONST_DIMOUSEFLAGS
  • CONST_DIMOUSEOFS
  • CONST_DINPUT
  • CONST_DINPUTERR
  • CONST_DIPHFLAGS
  • CONST_DISCLFLAGS
  • CONST_DISDDFLAGS
  • CONST_DISFFCFLAGS
  • CONST_DIVOICEFLAGS


CONST_DI8DEVICESUBTYPE

デバイス サブタイプを識別するために使用する。デバイス タイプとサブタイプを表すパック値は、DirectInputDeviceInstance8.GetDevType メソッドによって返される。また、DirectInputDevice8.GetCapabilities が返す DIDEVCAPS 型の lDevType メンバに含まれる。

Enum CONST_DI8DEVICESUBTYPE
    DI8DEVTYPE_LIMITEDGAMESUBTYPE       =      256 (&H100)
    DI8DEVTYPE1STPERSON_LIMITED         =      256 (&H100)
    DI8DEVTYPE1STPERSON_SHOOTER         =     1024 (&H400)
    DI8DEVTYPE1STPERSON_SIXDOF          =      768 (&H300)
    DI8DEVTYPE1STPERSON_UNKNOWN         =      512 (&H200)
    DI8DEVTYPEDEVICECTRL_COMMSSELECTION =      768 (&H300)
    DI8DEVTYPEDEVICECTRL_HARDWIRED      =     1024 (&H400)
    DI8DEVTYPEDEVICECTRL_UNKNOWN        =      512 (&H200)
    DI8DEVTYPEDRIVING_COMBINEDPEDALS    =      512 (&H200)
    DI8DEVTYPEDRIVING_DUALPEDALS        =      768 (&H300)
    DI8DEVTYPEDRIVING_HANDHELD          =     1280 (&H500)
    DI8DEVTYPEDRIVING_LIMITED           =      256 (&H100)
    DI8DEVTYPEDRIVING_THREEPEDALS       =     1024 (&H400)
    DI8DEVTYPEFLIGHT_LIMITED            =      256 (&H100)
    DI8DEVTYPEFLIGHT_RC                 =     1024 (&H400)
    DI8DEVTYPEFLIGHT_STICK              =      512 (&H200)
    DI8DEVTYPEFLIGHT_YOKE               =      768 (&H300)
    DI8DEVTYPEGAMEPAD_LIMITED           =      256 (&H100)
    DI8DEVTYPEGAMEPAD_STANDARD          =      512 (&H200)
    DI8DEVTYPEGAMEPAD_TILT              =      768 (&H300)
    DI8DEVTYPEJOYSTICK_LIMITED          =      256 (&H100)
    DI8DEVTYPEJOYSTICK_STANDARD         =      512 (&H200)
    DI8DEVTYPEKEYBOARD_J3100            =     3072 (&HC00)
    DI8DEVTYPEKEYBOARD_JAPAN106         =     2560 (&HA00)
    DI8DEVTYPEKEYBOARD_JAPANAX          =     2816 (&HB00)
    DI8DEVTYPEKEYBOARD_NEC98            =     1792 (&H700)
    DI8DEVTYPEKEYBOARD_NEC98106         =     2304 (&H900)
    DI8DEVTYPEKEYBOARD_NEC98LAPTOP      =     2048 (&H800)
    DI8DEVTYPEKEYBOARD_NOKIA1050        =     1280 (&H500)
    DI8DEVTYPEKEYBOARD_NOKIA9140        =     1536 (&H600)
    DI8DEVTYPEKEYBOARD_OLIVETTI         =      512 (&H200)
    DI8DEVTYPEKEYBOARD_PCAT             =      768 (&H300)
    DI8DEVTYPEKEYBOARD_PCENH            =     1024 (&H400)
    DI8DEVTYPEKEYBOARD_PCXT             =      256 (&H100)
    DI8DEVTYPEKEYBOARD_UNKNOWN          =        0 (&H000)
    DI8DEVTYPEMOUSE_ABSOLUTE            =     1536 (&H600)
    DI8DEVTYPEMOUSE_FINGERSTICK         =      768 (&H300)
    DI8DEVTYPEMOUSE_TOUCHPAD            =     1024 (&H400)
    DI8DEVTYPEMOUSE_TRACKBALL           =     1280 (&H500)
    DI8DEVTYPEMOUSE_TRADITIONAL         =      512 (&H200)
    DI8DEVTYPEMOUSE_UNKNOWN             =      256 (&H100)
    DI8DEVTYPEREMOTE_UNKNOWN            =      512 (&H200)
    DI8DEVTYPESCREENPTR_LIGHTGUN        =      768 (&H300)
    DI8DEVTYPESCREENPTR_LIGHTPEN        =     1024 (&H400)
    DI8DEVTYPESCREENPTR_TOUCH           =     1280 (&H500)
    DI8DEVTYPESCREENPTR_UNKNOWN         =      512 (&H200)
    DI8DEVTYPESUPPLEMENTAL_2NDHANDCONTROLLER = 768 (&H300)
    DI8DEVTYPESUPPLEMENTAL_COMBINEDPEDALS  =  2560 (&HA00)
    DI8DEVTYPESUPPLEMENTAL_DUALPEDALS      =  2816 (&HB00)
    DI8DEVTYPESUPPLEMENTAL_HANDTRACKER     =  1280 (&H500)
    DI8DEVTYPESUPPLEMENTAL_HEADTRACKER     =  1024 (&H400)
    DI8DEVTYPESUPPLEMENTAL_RUDDERPEDALS    =  3328 (&HD00)
    DI8DEVTYPESUPPLEMENTAL_SHIFTER         =  1792 (&H700)
    DI8DEVTYPESUPPLEMENTAL_SHIFTSTICKGATE  =  1536 (&H600)
    DI8DEVTYPESUPPLEMENTAL_SPLITTHROTTLE   =  2304 (&H900)
    DI8DEVTYPESUPPLEMENTAL_THREEPEDALS     =  3072 (&HC00)
    DI8DEVTYPESUPPLEMENTAL_THROTTLE        =  2048 (&H800)
    DI8DEVTYPESUPPLEMENTAL_UNKNOWN         =   512 (&H200)
    DIDEVTYPE_HID                          = 65536 (&H10000)
End Enum

定数

DI8DEVTYPEJOYSTICK_ENHANCED
標準ジョイスティックより多くの軸または視点コントローラを持つジョイスティック。
DI8DEVTYPE1STPERSON_LIMITED
アクション マッピング対象のデバイス オブジェクトの最小数を指定しないデバイス。
DI8DEVTYPE1STPERSON_SHOOTER
対面型のシューティング ゲーム用に設計されたデバイス。
DI8DEVTYPE1STPERSON_SIXDOF
6 段階 (3 つの横方向軸と 3 つの回転軸) の自由を備えたデバイス。
DI8DEVTYPE1STPERSON_UNKNOWN
不明なサブタイプ。
DI8DEVTYPEDEVICECTRL_COMMSSELECTION
通信の選択に使用されるコントロール。
DI8DEVTYPEDEVICECTRL_HARDWIRED
デフォルトの構成を使用する必要があり、マッピングを変更できないデバイス。
DI8DEVTYPEDEVICECTRL_UNKNOWN
不明なサブタイプ。
DI8DEVTYPEDRIVING_COMBINEDPEDALS
単一の軸からアクセルとブレーキ ペダルの値を報告するステアリング デバイス。
DI8DEVTYPEDRIVING_DUALPEDALS
別々の軸からアクセルとブレーキ ペダルの値を報告するステアリング デバイス。
DI8DEVTYPEDRIVING_HANDHELD
ハンドヘルドのステアリング デバイス。
DI8DEVTYPEDRIVING_LIMITED
アクション マッピング対象のデバイス オブジェクトの最小数を指定しないステアリング デバイス。
DI8DEVTYPEDRIVING_THREEPEDALS
別々の軸からアクセル、ブレーキ、およびクラッチ ペダルの値を報告するステアリング デバイス。
DI8DEVTYPEFLIGHT_LIMITED
アクション マッピング対象のデバイス オブジェクトの最小数を指定しないフライト コントローラ。
DI8DEVTYPEFLIGHT_RC
模型飛行機のリモート コントロールに基づくフライト デバイス。
DI8DEVTYPEFLIGHT_STICK
ジョイスティック。
DI8DEVTYPEFLIGHT_YOKE
操縦輪。
DI8DEVTYPEGAMEPAD_LIMITED
アクション マッピング対象のデバイス オブジェクトの最小数を指定しないゲームパッド。
DI8DEVTYPEGAMEPAD_STANDARD
アクション マッピング対象のデバイス オブジェクトの最小数を指定しない標準ゲームパッド。
DI8DEVTYPEGAMEPAD_TILT
コントローラの姿勢から x 軸と y 軸のデータを報告するゲームパッド。
DI8DEVTYPEJOYSTICK_LIMITED
アクション マッピング対象のデバイス オブジェクトの最小数を指定しないジョイスティック。
DI8DEVTYPEJOYSTICK_STANDARD
アクション マッピング対象のデバイス オブジェクトの最小数を指定する標準ジョイスティック。
DI8DEVTYPEKEYBOARD_J3100
日本語 J3100 キーボード。
DI8DEVTYPEKEYBOARD_JAPAN106
日本語 106 キー キーボード。
DI8DEVTYPEKEYBOARD_JAPANAX
日本語 AX キーボード。
DI8DEVTYPEKEYBOARD_NEC98
日本語 NEC PC98 キーボード。
DI8DEVTYPEKEYBOARD_NEC98106
日本語 NEC PC98 106 キー キーボード。
DI8DEVTYPEKEYBOARD_NEC98LAPTOP
日本語 NEC PC98 ラップトップ キーボード。
DI8DEVTYPEKEYBOARD_NOKIA1050
Nokia 1050 キーボード。
DI8DEVTYPEKEYBOARD_NOKIA9140
Nokia 9140 キーボード。
DI8DEVTYPEKEYBOARD_OLIVETTI
Olivetti 102 キー キーボード。
DI8DEVTYPEKEYBOARD_PCAT
IBM PC/AT 84 キー キーボード。
DI8DEVTYPEKEYBOARD_PCENH
IBM PC 拡張 101/102 キー式キーボードまたは Microsoft® ナチュラル キーボード
DI8DEVTYPEKEYBOARD_PCXT
IBM PC/XT 83 キー キーボード。
DI8DEVTYPEKEYBOARD_UNKNOWN
不明なサブタイプ。
DI8DEVTYPEMOUSE_ABSOLUTE
絶対軸データを返すマウス。
DI8DEVTYPEMOUSE_FINGERSTICK
フィンガースティック。
DI8DEVTYPEMOUSE_TOUCHPAD
タッチパッド。
DI8DEVTYPEMOUSE_TRACKBALL
トラックボール。
DI8DEVTYPEMOUSE_TRADITIONAL
従来型マウス。
DI8DEVTYPEMOUSE_UNKNOWN
不明なサブタイプ。
DI8DEVTYPEREMOTE_UNKNOWN
リモート コントロール デバイス。定義済みのリモート コントロール デバイス サブタイプはこれのみである。
DI8DEVTYPESCREENPTR_LIGHTGUN
ライト ガン。
DI8DEVTYPESCREENPTR_LIGHTPEN
ライト ペン。
DI8DEVTYPESCREENPTR_TOUCH
タッチ スクリーン。
DI8DEVTYPESCREENPTR_UNKNOWN
不明なサブタイプ。
DI8DEVTYPESUPPLEMENTAL_2NDHANDCONTROLLER
セカンダリ ハンドヘルド コントローラ。
DI8DEVTYPESUPPLEMENTAL_COMBINEDPEDALS
主機能として、単一の軸からアクセルとブレーキ ペダルの値を報告するデバイス。
DI8DEVTYPESUPPLEMENTAL_DUALPEDALS
主機能として、別々の軸からアクセルとブレーキ ペダルの値を報告するデバイス。
DI8DEVTYPESUPPLEMENTAL_HANDTRACKER
手の移動を追跡するデバイス。
DI8DEVTYPESUPPLEMENTAL_HEADTRACKER
頭の移動を追跡するデバイス。
DI8DEVTYPESUPPLEMENTAL_RUDDERPEDALS
方向舵ペダルを備えたデバイス。
DI8DEVTYPESUPPLEMENTAL_SHIFTER
軸からギア選択を報告するデバイス。
DI8DEVTYPESUPPLEMENTAL_SHIFTSTICKGATE
ボタン状態からギア選択を報告するデバイス。
DI8DEVTYPESUPPLEMENTAL_SPLITTHROTTLE
主機能として、2 つ以上のスロットル値を報告するデバイス。その他のコントロールを持つ場合がある。
DI8DEVTYPESUPPLEMENTAL_THREEPEDALS
主機能として、別々の軸からアクセル、ブレーキ、およびクラッチ ペダルの値を報告するデバイス。
DI8DEVTYPESUPPLEMENTAL_THROTTLE
主機能として、単一のスロットル値を報告するデバイス。その他のコントロールを持つ場合がある。
DI8DEVTYPESUPPLEMENTAL_UNKNOWN
不明なサブタイプ。
DIDEVTYPE_HID
HID (Human Interface Device)。

参照

CONST_DI8DEVICETYPE


CONST_DI8DEVICETYPE

入力デバイスのクラスとタイプを識別するために使用する。列挙するクラスまたはタイプを指定するには、これらの定数のいずれかを deviceType パラメータとして DirectInput8.GetDIDevices メソッドに渡す。デバイス タイプとサブタイプを表すパック値は、DirectInputDeviceInstance8.GetDevType メソッドによって返される。また、DirectInputDevice8.GetCapabilities が返す DIDEVCAPS 型の lDevType メンバに含まれる。

Enum CONST_DI8DEVICETYPE
    DI8DEVCLASS_ALL          =  0
    DI8DEVCLASS_DEVICE       =  1
    DI8DEVCLASS_GAMECTRL     =  4
    DI8DEVCLASS_KEYBOARD     =  3
    DI8DEVCLASS_POINTER      =  2
    DI8DEVTYPE_1STPERSON     = 24 (&H18)
    DI8DEVTYPE_DEVICE        = 17 (&H11)
    DI8DEVTYPE_DEVICECTRL    = 25 (&H19)
    DI8DEVTYPE_DRIVING       = 22 (&H16)
    DI8DEVTYPE_FLIGHT        = 23 (&H17)
    DI8DEVTYPE_GAMEPAD       = 21 (&H15)
    DI8DEVTYPE_JOYSTICK      = 20 (&H14)
    DI8DEVTYPE_KEYBOARD      = 19 (&H13)
    DI8DEVTYPE_MOUSE         = 18 (&H12)
    DI8DEVTYPE_REMOTE        = 27 (&H1B)
    DI8DEVTYPE_SCREENPOINTER = 26 (&H1A)
    DI8DEVTYPE_SUPPLEMENTAL  = 28 (&H1C)
End Enum

定数

DI8DEVCLASS_ALL
すべてのデバイス。
DI8DEVCLASS_DEVICE
ほかのクラスに分類されないすべてのデバイス。
DI8DEVCLASS_GAMECTRL
すべてのゲーム コントローラ。
DI8DEVCLASS_KEYBOARD
すべてのキーボード。DI8DEVTYPE_KEYBOARD と同義である。
DI8DEVCLASS_POINTER
DI8DEVTYPE_MOUSE および DI8DEVTYPE_SCREENPOINTER タイプのすべてのデバイス。
DI8DEVTYPE_1STPERSON
対面型のアクション ゲーム デバイス。
DI8DEVTYPE_DEVICE
別のカテゴリに属さないデバイス。
DI8DEVTYPE_DEVICECTRL
アプリケーションのコンテキストから別タイプのデバイスの制御に使用される入力デバイス。
DI8DEVTYPE_DRIVING
ステアリング用デバイス。
DI8DEVTYPE_FLIGHT
フライト シミュレーション用コントローラ。
DI8DEVTYPE_GAMEPAD
ゲームパッド。
DI8DEVTYPE_JOYSTICK
ジョイスティック。
DI8DEVTYPE_KEYBOARD
キーボードまたはキーボード類似デバイス。
DI8DEVTYPE_MOUSE
マウスまたはマウス類似デバイス (トラックボールなど)。
DI8DEVTYPE_REMOTE
リモート コントロール デバイス。
DI8DEVTYPE_SCREENPOINTER
スクリーン ポインタ。
DI8DEVTYPE_SUPPLEMENTAL
ホイールと共に使用するペダルなど、アプリケーションのメイン コントロールに適さない機能を備えた特殊デバイス。

参照

CONST_DI8DEVICESUBTYPE


CONST_DIAFLAGS

DIACTION 型の lFlags メンバ内で使用され、アクションのマップ方法を指定する。

Enum CONST_DIAFLAGS
    DIA_APPMAPPED     = 2
    DIA_APPNOMAP      = 4
    DIA_FORCEFEEDBACK = 1
    DIA_NORANGE       = 8
End Enum

定数

DIA_APPMAPPED
DIACTION 型の lObjID メンバが有効であり、DirectInputDevice8.BuildActionMap はアプリケーション定義マッピングを上書きしない。
DIA_APPNOMAP
このアクションはマップしない。
DIA_FORCEFEEDBACK
アクションをアクチュエータまたはトリガにマップする。
DIA_NORANGE
このアクションにはデフォルトの範囲を設定しない。このフラグは絶対軸アクションにのみ設定できる。


CONST_DIAHFLAGS

DIACTION 型の lHow メンバ内で使用され、アクションのマップ方法を報告する。

Enum CONST_DIAHFLAGS
    DIAH_APPREQUESTED =           2
    DIAH_DEFAULT      =          32 (&H20)
    DIAH_ERROR        = -2147483648 (&H80000000)
    DIAH_HWAPP        =           4
    DIAH_HWDEFAULT    =           8
    DIAH_UNMAPPED     =           0
    DIAH_USERCONFIG   =           1
End Enum

定数

DIAH_APPREQUESTED
アプリケーションがマッピングを構成し、DirectInputDevice8.BuildActionMap の呼び出し時にデバイス (guidInstance) およびデバイス オブジェクト (lObjID) が指定された。
DIAH_DEFAULT
ほかのマッピング情報がないため、Microsoft® DirectInput® がマッピングを決定した。
DIAH_ERROR
エラーが発生した。アクションがデバイスのコントロールと一致しない。アクション マップの設定時に、このアクションは無視される。
DIAH_HWAPP
このゲームのハードウェア メーカーがマッピングを指定した。
DIAH_HWDEFAULT
このジャンルのハードウェア メーカーがマッピングを指定した。
DIAH_UNMAPPED
適切なデバイス オブジェクトが見つからなかった。
DIAH_USERCONFIG
ユーザーがマッピングを構成した。


CONST_DICDFLAGS

DirectInput8.ConfigureDevices の flags パラメータで使用され、プロパティ シートのモードを指定する。

Enum CONST_DICDFLAGS
    DICD_DEFAULT = 0
    DICD_EDIT    = 1
End Enum

定数

DICD_DEFAULT
プロパティ シートを表示専用モードで開く。
DICD_EDIT
プロパティ シートを編集モードで開く。このモードでは、ユーザーがアクションとコントロールのマッピングを変更できる。呼び出しが戻ると、アプリケーションは現在のデバイスがもう有効ではないと仮定して、デバイス インターフェイスを解放し、DirectInput8.GetDevicesBySemantics を呼び出してそのインターフェイスを初期化する。


CONST_DICOMMONDATAFORMATS

DirectInputDevice8.SetCommonDataFormat メソッドの format パラメータにデータ形式を指定する。

Enum CONST_DICOMMONDATAFORMATS
    DIFORMAT_JOYSTICK  =  3
    DIFORMAT_JOYSTICK2 =  4
    DIFORMAT_KEYBOARD  =  1
    DIFORMAT_MOUSE     =  2
    DIFORMAT_MOUSE2    =  5
End Enum

定数

DIFORMAT_JOYSTICK
状態データを DIJOYSTATE 型に受け取るジョイスティック。
DIFORMAT_JOYSTICK2
状態データを DIJOYSTATE2 型に受け取る拡張機能付きジョイスティック。
DIFORMAT_KEYBOARD
状態データを DIKEYBOARDSTATE 型に受け取るキーボード。
DIFORMAT_MOUSE
状態データを DIMOUSESTATE 型に受け取るマウス。
DIFORMAT_MOUSE2
状態データを DIMOUSESTATE2 型に受け取るマウス。


CONST_DICONDITIONFLAGS

DIEFFECT 型の conditionFlags メンバに使用され、フォース フィードバック エフェクトの軸と方向を設定する。

Enum CONST_DICONDITIONFLAGS
    DICONDITION_USE_BOTH_AXES = 1
    DICONDITION_USE_DIRECTION = 2
End Enum

定数

DICONDITION_USE_BOTH_AXES
DIEFFECT 型の conditionX メンバおよび conditionY メンバ両方のデータを使用する。
DICONDITION_USE_DIRECTION
DIEFFECT 型の conditionX メンバのみのデータを使用する。


CONST_DIDALFLAGS

アクション マッピング プロパティ シート内のテキスト配置を指定するために使用される。

Enum CONST_DIDALFLAGS
    DIDAL_BOTTOMALIGNED = 8
    DIDAL_CENTERED      = 0
    DIDAL_LEFTALIGNED   = 1
    DIDAL_MIDDLE        = 0
    DIDAL_RIGHTALIGNED  = 2
    DIDAL_TOPALIGNED    = 4
End Enum

定数

DIDAL_BOTTOMALIGNED
テキストを下枠線に揃える。
DIDAL_CENTERED
テキストを水平方向の中央に寄せる。
DIDAL_LEFTALIGNED
テキストを左枠線に揃える。
DIDAL_MIDDLE
テキストを垂直方向の中央に寄せる。
DIDAL_RIGHTALIGNED
テキストを右枠線に揃える。
DIDAL_TOPALIGNED
テキストを上枠線に揃える。


CONST_DIDATAFORMATFLAGS

DIDATAFORMAT 型の lFlags メンバに使用され、データ形式の追加属性を表す。

Enum CONST_DIDATAFORMATFLAGS
    DIDF_ABSAXIS = 1
    DIDF_RELAXIS = 2
End Enum

定数

DIDF_ABSAXIS
軸は絶対モードにある。このフラグをデータ形式に設定することは、DirectInputDevice8.SetProperty メソッドを使って軸モード プロパティを手動で設定するのと等しい。この値を DIDF_RELAXIS フラグと組み合わせることはできない。
DIDF_RELAXIS
軸は相対モードにある。このフラグをデータ形式に設定することは、DirectInputDevice8.SetProperty メソッドを使って軸モード プロパティを手動で設定するのと等しい。この値を DIDF_ABSAXIS フラグと組み合わせることはできない。


CONST_DIDBAMFLAGS

DirectInputDevice8.BuildActionMap メソッドで使用される。

Enum CONST_DIDBAMFLAGS
    DIDBAM_DEFAULT    = 0
    DIDBAM_HWDEFAULTS = 4
    DIDBAM_INITIALIZE = 2
    DIDBAM_PRESERVE   = 1
End Enum

定数

DIDBAM_DEFAULT
アプリケーション指定のマッピング (DIACTION 型に DIA_APPMAPPED フラグを持つマッピング) を除くすべてのマッピングを上書きする。
DIDBAM_HWDEFAULTS
アプリケーション指定のマッピングを含め、すべてのマッピングを上書きする。このフラグは DIDBAM_INITIALIZE に類似しているが、ユーザーがマップしたアクションは、デバイス ドライバまたは Microsoft® DirectInput® に指定されたデフォルト アクションで自動的に上書きされる。
DIDBAM_INITIALIZE
アプリケーション指定のマッピングを含め、すべてのマッピングを上書きする。
DIDBAM_PRESERVE
このデバイス、またはその他の構成済みデバイスに割り当てられた現在のマッピングを保存する。


CONST_DIDEVCAPSFLAGS

DIDEVCAPS 型の lFlags メンバに使用され、Microsoft® DirectInput® デバイスを表す。

Enum CONST_DIDEVCAPSFLAGS
    DIDC_ALIAS              =  65536 (&H10000)
    DIDC_ATTACHED           =      1
    DIDC_DEADBAND           =  16384 (&H4000)
    DIDC_EMULATED           =      4
    DIDC_FFATTACK           =    512 (&H200)
    DIDC_FFFADE             =   1024 (&H400)
    DIDC_FORCEFEEDBACK      =    256 (&H100)
    DIDC_PHANTOM            = 131072 (&H20000)
    DIDC_POLLEDDATAFORMAT   =      8
    DIDC_POLLEDDEVICE       =      2
    DIDC_POSNEGCOEFFICIENTS =   4096 (&H1000)
    DIDC_POSNEGSATURATION   =   8192 (&H2000)
    DIDC_SATURATION         =   2048 (&H800)
End Enum

定数

DIDC_ALIAS
デバイスは、別の DirectInput デバイスの複製である。別名のデバイスは、デフォルトでは DirectInput8.GetDIDevices によって列挙されない。
DIDC_ATTACHED
デバイスは、物理的にアタッチ状態にある。
DIDC_DEADBAND
デバイスは、少なくとも 1 つのフォース フィードバック条件でデッドバンドをサポートしている。
DIDC_EMULATED
このフラグが設定されると、データは、HID (Human Interface Device) などのユーザー モード デバイス インターフェイス、またはほかのリング 3 の手段により入力される。フラグが設定されない場合、データはカーネル モード ドライバから直接入力される。
DIDC_FFATTACK
フォース フィードバック システムは、少なくとも 1 つのエフェクトに対するアタック パラメータをサポートする。デバイスがアタックをサポートしない場合、DIENVELOPE 型の lAttackLevel メンバと lAttackTime メンバは、デバイスにより無視される。
DIDC_FFFADE
フォース フィードバック システムは、少なくとも 1 つのエフェクトに対するフェード パラメータをサポートする。デバイスがフェードをサポートしない場合、DIENVELOPE 型の lFadeLevel メンバと lFadeTime メンバは、デバイスにより無視される。
DIDC_FORCEFEEDBACK
デバイスは、フォース フィードバックをサポートする。
DIDC_PHANTOM
このデバイスは存在しない。将来存在する可能性のあるデバイス用のプレースホルダである。仮想デバイスは、デフォルトでは DirectInput8.GetDIDevices によって列挙されない。
DIDC_POLLEDDATAFORMAT
現状のデータ形式で少なくとも 1 つのオブジェクトが、割り込み駆動ではなく、ポーリングされる。このようなオブジェクトの場合、アプリケーションはデータを取得するために DirectInputDevice8.Poll メソッドを明示的に呼び出さなければならない。
DIDC_POLLEDDEVICE
デバイス上の少なくとも 1 つのオブジェクトが、割り込み駆動ではなく、ポーリングされる。このようなオブジェクトの場合、アプリケーションはデータを取得するために DirectInputDevice8.Poll メソッドを明示的に呼び出さなければならない。HID デバイスは、ポーリング オブジェクトと非ポーリング オブジェクトを混在して格納できる。
DIDC_POSNEGCOEFFICIENTS
フォース フィードバック システムは、少なくとも 1 つの条件に対して条件の 2 つの係数値をサポートする (一方は、軸の正移動、他方は、軸の負移動)。デバイスが両方の係数をサポートしていなければ、DICONDITION 型の負の係数は無視される。
DIDC_POSNEGSATURATION
フォース フィードバック システムは、少なくとも 1 つの条件に対して、正負の両方のフォース出力に対する最大飽和をサポートする。デバイスが両方の飽和値をサポートしていなければ、DICONDITION 型の負の飽和値は無視される。
DIDC_SATURATION
フォース フィードバック システムは、少なくとも 1 つの条件に対して条件エフェクトの飽和をサポートする。デバイスが飽和をサポートしていなければ、ある条件の下で生成されるフォースは、デバイスが生成できる最大フォースによってのみ制限される。

参照

CONST_DIEFTFLAGS


CONST_DIDEVICEOBJINSTANCEFLAGS

デバイス オブジェクトの機能を表すために使用される。この列挙のメンバは、DirectInputDeviceObjectInstance.GetFlags メソッドにより取得される。また、DirectInputDevice8.SetDataFormat メソッドに渡される DIOBJECTDATAFORMAT 型内にも存在する。

Enum CONST_DIDEVICEOBJINSTANCEFLAGS
    DIDOI_ASPECTACCEL     =   768 (&H300)
    DIDOI_ASPECTFORCE     =  1024 (&H400)
    DIDOI_ASPECTMASK      =  3840 (&HF00)
    DIDOI_ASPECTPOSITION  =   256 (&H100)
    DIDOI_ASPECTVELOCITY  =   512 (&H200)
    DIDOI_FFACTUATOR      =     1
    DIDOI_FFEFFECTTRIGGER =     2
    DIDOI_GUIDISUSAGE      =  4096 (&H1000)
    DIDOI_POLLED          = 32768 (&H8000)
End Enum

定数

DIDOI_ASPECTACCEL
オブジェクトは加速度情報を報告する。
DIDOI_ASPECTFORCE
オブジェクトはフォース情報を報告する。
DIDOI_ASPECTMASK
アスペクト情報を報告するためのビット。1 つのオブジェクトは最大 1 つのアスペクトしか表すことができない。
DIDOI_ASPECTPOSITION
オブジェクトは位置情報を報告する。
DIDOI_ASPECTVELOCITY
オブジェクトは速度情報を報告する。
DIDOI_FFACTUATOR
オブジェクトは、フォース フィードバック エフェクトを自身に適用させることができる。
DIDOI_FFEFFECTTRIGGER
オブジェクトは、フォース フィードバック エフェクトの再生をトリガする。
DIDOI_GUIDISUSAGE
DIOBJECTDATAFORMAT.strGuid には、HID (Human Interface Device) の使用状況と使用ページがパック形式で格納される。
DIDOI_POLLED
オブジェクトは、DirectInputDevice8.Poll メソッドが呼び出されるまでデータを返さない。


CONST_DIDFTFLAGS

DirectInputDevice8.GetDeviceObjectsEnum メソッドの flags パラメータで使用され、列挙するデバイス オブジェクトのタイプを指定する。また、これらの値が DirectInputDeviceObjectInstance.GetFlags メソッドによって返される場合は、デバイス オブジェクトの能力を表す。

Enum CONST_DIDFTFLAGS
    DIDFT_ABSAXIS         =         2
    DIDFT_ALL             =         0
    DIDFT_ANYINSTANCE     =  16776960 (&HFFFF00)
    DIDFT_AXIS            =         3
    DIDFT_BUTTON          =        12
    DIDFT_COLLECTION      =        64 (&H40)
    DIDFT_FFACTUATOR      =  16777216 (&H1000000)
    DIDFT_FFEFFECTTRIGGER =  33554432 (&H2000000)
    DIDFT_INSTANCEMASK    =  16776960 (&HFFFF00)
    DIDFT_NOCOLLECTION    =  16776960 (&HFFFF00)
    DIDFT_NODATA          =       128 (&H80)
    DIDFT_OUTPUT          = 268435456 (&H10000000)
    DIDFT_POV             =        16 (&H10)
    DIDFT_PSHBUTTON       =         4
    DIDFT_RELAXIS         =         1
    DIDFT_TGLBUTTON       =         8
End Enum

定数

DIDFT_ABSAXIS
絶対軸。
DIDFT_ALIAS
HID (Human Interface Device) 使用エイリアスによって識別されるコントロール。このフラグは、HID 準拠の USB デバイスに対してのみ適用される。
DIDFT_ALL
すべてのオブジェクト。
DIDFT_ANYINSTANCE
DIDFT_AXIS または DIDFT_BUTTON などのほかの基準を満たすように列挙された最初のインスタンスを使用すること。
DIDFT_AXIS
絶対軸、相対軸のどちらか。
DIDFT_BUTTON
プッシュ ボタンまたはトグル ボタン。
DIDFT_COLLECTION
HID (Human Interface Device) リンク コレクション。HID リンク コレクションは、独自のデータを生成しない。
DIDFT_FFACTUATOR
フォース フィードバック アクチュエータを含むオブジェクト。つまり、フォースをこのオブジェクトに適用することができる。
DIDFT_FFEFFECTTRIGGER
フォース フィードバック エフェクトをトリガするために使用できるオブジェクト。
DIDFT_INSTANCEMASK
DIDFT_ANYINSTANCE と同じ。
DIDFT_NOCOLLECTION
あらゆる HID リンク コレクションに属しない、つまり、DirectInputDeviceObjectInstance.GetCollectionNumber がゼロを返すオブジェクト。
DIDFT_NODATA
データを生成しないオブジェクト。
DIDFT_OUTPUT
DirectInputDevice8.SendDeviceData メソッドを利用することによって、データを送ることができるオブジェクト。
DIDFT_POV
視点コントローラ。
DIDFT_PSHBUTTON
プッシュ ボタン。プッシュ ボタンは、ユーザーが押したときにダウン、ユーザーが離したときにアップと報告される。
DIDFT_RELAXIS
相対軸。
DIDFT_TGLBUTTON
トグル ボタン。トグル ボタンは、ユーザーが押したときにダウンと報告され、ユーザーが再度そのボタンを押すまでその状態に留まる。
DIDFT_VENDORDEFINED
メーカーにより定義されるタイプのオブジェクト。


CONST_DIDGDDFLAGS

DirectInputDevice8.GetDeviceData メソッドの flags パラメータで使用され、データの取得方法を制御する。

Enum CONST_DIDGDDFLAGS
    DIGDD_DEFAULT = 0
    DIGDD_PEEK    = 1
End Enum

定数

DIGDD_DEFAULT
取得した項目をバッファから削除する。
DIGDD_PEEK
取得した項目をバッファから削除しない。これ以降の GetDeviceData 呼び出しで、同じデータを読み取ることができる。


CONST_DIDIFTFLAGS

DIDEVICEIMAGEINFO 型の flags メンバで使用され、ファイルのタイプを指定する。

Enum CONST_DIDIFTFLAGS
    DIDIFT_CONFIGURATION =     1
    DIDIFT_OVERLAY       =     2
End Enum

定数

DIDIFT_CONFIGURATION
ファイルは、デバイスに対するアクションの現在構成を表示するために使用される。オーバーレイ イメージの座標は、構成イメージの左上隅を起点とする相対座標である。
DIDIFT_OVERLAY
ファイルは、構成イメージのオーバーレイである。OverlayOffset、OverlayRect、ObjID、CalloutLine、CalloutRect、および TextAlign の各メンバは有効であり、これらに格納されたデータを使って、デバイスの単一コントロールのオーバーレイとコールアウト情報が表示される。


CONST_DIDSAMFLAGS

DirectInputDevice8.SetActionMap メソッドで使用される。

Enum CONST_DIDSAMFLAGS
    DIDSAM_DEFAULT   = 0
    DIDSAM_NOUSER    = 1
    DIDSAM_FORCESAVE = 2
End Enum

定数

DIDSAM_DEFAULT
このユーザーのアクション マップを設定する。そのマップが現在のマップと異なる場合、新しい設定がディスクに保存される。
DIDSAM_FORCESAVE
構成を常にディスクに保存する。
DIDSAM_NOUSER
デフォルトの構成プロパティ シートでこのデバイスのユーザー所有権をリセットする。ユーザー所有権をリセットしても、現在のアクション マップは削除されない。


CONST_DIEDBSFLFLAGS

DirectInput8.GetDevicesBySemantics メソッドで使用され、列挙の範囲を指定する。

Enum CONST_DIEDBSFLFLAGS
    DIEDBSFL_ATTACHEDONLY       =     0
    DIEDBSFL_AVAILABLEDEVICES   =  4096 (&H1000)
    DIEDBSFL_FORCEFEEDBACK      =   256 (&H100)
    DIEDBSFL_MULTIMICEKEYBOARDS =  8192 (&H2000)
    DIEDBSFL_NONGAMINGDEVICES   = 16384 (&H4000)
    DIEDBSFL_THISUSER           =    16 (&H10)
    DIEDBSFL_VALID              =  4368 (&H1110)
End Enum

定数

DIEDBSFL_ATTACHEDONLY
アタッチ状態にあり、インストール済みのデバイスだけを列挙する。
DIEDBSFL_AVAILABLEDEVICES
未所有かつインストール済みのデバイスだけを列挙する。
DIEDBSFL_FORCEFEEDBACK
フォース フィードバックをサポートするデバイスだけを列挙する。
DIEDBSFL_MULTIMICEKEYBOARDS
セカンダリ (非システム) キーボードおよびマウス デバイスだけを列挙する。
DIEDBSFL_NONGAMINGDEVICES
ゲーム デバイスとして使用することが主な用途ではない HID 適合デバイスだけを列挙する。USB スピーカや一部のキーボード上のマルチメディア ボタンなどのデバイスが、この値に含まれる。
DIEDBSFL_THISUSER
str1 によって識別されるユーザー用のインストール済みのすべてのデバイス、および未所有のすべてのデバイスを列挙する。
DIEDBSFL_VALID
アプリケーションは使用しない。


CONST_DIEFFFLAGS

DIEFFECT 型の lFlags メンバで使用される。

Enum CONST_DIEFFFLAGS
    DIEFF_CARTESIAN     = 16 (&H10)
    DIEFF_OBJECTOFFSETS =  2
    DIEFF_POLAR         = 32 (&H20)
End Enum

定数

DIEFF_CARTESIAN
エフェクトの方向は、デカルト座標で指定される。DIEFFECT.x と DIEFFECT.y に有効な値が格納される。
DIEFF_OBJECTOFFSETS
DIEFFECT の lTriggerButton メンバの値は、デバイスのデータ構造に含まれるボタンのオフセットである。
DIEFF_POLAR
エフェクトの方向は、極座標で指定される。DIEFFECT.x に有効な値が格納される。

注意

DirectInputDevice8.CreateEffect および DirectInputDevice8.CreateCustomEffect のデフォルトの動作は、DIEFFECT.lFlags に (DIEFF_OBJECTOFFSETS Or DIEFF_POLAR) が含まれる場合と同様に、エフェクトを生成する。つまり、これらのフラグを指定する必要はない。


CONST_DIEFTFLAGS

フォース フィードバック エフェクトのタイプと能力を表すために使用される。これらのフラグは、DirectInputDevice8.GetEffectsEnum メソッドでエフェクトの列挙対象を 1 つ以上のプライマリ タイプに制限する。また、DirectInputEnumEffects.GetType メソッドでもこれらのメンバが返される。

Enum CONST_DIEFTFLAGS
    DIEFT_ALL                =     0
    DIEFT_CONDITION          =     4
    DIEFT_CONSTANTFORCE      =     1
    DIEFT_CUSTOMFORCE        =     5
    DIEFT_DEADBAND           = 16384 (&H4000)
    DIEFT_FFATTACK           =   512 (&H200)
    DIEFT_FFFADE             =  1024 (&H400)
    DIEFT_HARDWARE           =   255 (&HFF)
    DIEFT_PERIODIC           =     3
    DIEFT_POSNEGCOEFFICIENTS =  4096 (&H1000)
    DIEFT_POSNEGSATURATION   =  8192 (&H2000)
    DIEFT_RAMPFORCE          =     2
    DIEFT_SATURATION         =  2048 (&H800)
End Enum

定数

DIEFT_ALL
すべてのエフェクトを列挙する。
DIEFT_CONDITION
エフェクトは条件である。または、条件を列挙する。
DIEFT_CONSTANTFORCE
エフェクトはコンスタント フォースである。または、コンスタント フォースを列挙する。
DIEFT_CUSTOMFORCE
エフェクトはカスタム フォースである。または、カスタム フォースを列挙する。
DIEFT_DEADBAND
エフェクトはデッドバンドをサポートする。
DIEFT_FFATTACK
エフェクトはアタックをサポートする。
DIEFT_FFFADE
エフェクトはフェードをサポートする。
DIEFT_HARDWARE
エフェクトはハードウェアに固有である。または、ハードウェア エフェクトを列挙する。
DIEFT_PERIODIC
エフェクトは周期的である。または、周期的エフェクトを列挙する。
DIEFT_POSNEGCOEFFICIENTS
条件は正と負の係数を個別にサポートする。
DIEFT_POSNEGSATURATION
エフェクトは正と負の飽和を個別にサポートする。
DIEFT_RAMPFORCE
エフェクトは傾斜フォースである。または、傾斜フォースを列挙する。
DIEFT_SATURATION
エフェクトは飽和値をサポートする。

参照

CONST_DIDEVCAPSFLAGS


CONST_DIEGESFLAGS

DirectInputEffect.GetEffectStatus メソッドにより返される。

Enum CONST_DIEGESFLAGS
    DIEGES_EMULATED = 2
    DIEGES_PLAYING  = 1
End Enum

定数

DIEGES_EMULATED
エフェクトはエミュレートされる。
DIEGES_PLAYING
エフェクトは再生中である。


CONST_DIENUMDEVICESFLAGS

DirectInput8.GetDIDevices メソッドの flags パラメータに使用され、すべてのデバイスを列挙するか、またはアタッチ状態にあるデバイスのみを列挙するかを指定する。

Enum CONST_DIENUMDEVICESFLAGS
    DIEDFL_ALLDEVICES      =      0
    DIEDFL_ATTACHEDONLY    =      1
    DIEDFL_FORCEFEEDBACK   =    256 (&H100)
    DIEDFL_INCLUDEALIASES  =  65536 (&H10000)
    DIEDFL_INCLUDEHIDDEN   = 262144 (&H40000)
    DIEDFL_INCLUDEPHANTOMS = 131072 (&H20000)
End Enum

定数

DIEDFL_ALLDEVICES
すべてのインストール済みデバイスを列挙する。これがデフォルト モードである。
DIEDFL_ATTACHEDONLY
アタッチ状態にあり、インストール済みのデバイスだけ列挙される。
DIEDFL_FORCEFEEDBACK
フォース フィードバックをサポートするデバイスだけを列挙する。
DIEDFL_INCLUDEALIASES
ほかのデバイスのエイリアスであるデバイスを含める。
DIEDFL_INCLUDEHIDDEN
隠しデバイスを含める。隠しデバイスの詳細については、「CONST_DIDEVCAPSFLAGS」を参照すること。
DIEDFL_INCLUDEPHANTOMS
仮想デバイス (プレースホルダ) を含める。


CONST_DIEPFLAGS

エフェクトに関するさまざまなフラグ。一部のメンバは、DirectInputEffect.SetParameters メソッドに渡され、設定対象のパラメータ、およびエフェクトのその後の動作を指定する。また、一部のメンバは、DirectInputEnumEffects.GetStaticParams メソッドおよび DirectInputEnumEffects.GetDynamicParams メソッドにより返され、パラメータのサポートを表す。

Enum CONST_DIEPFLAGS
    DIEP_ALLPARAMS             =        1023 (&H3FF)
    DIEP_AXES                  =          32 (&H20)
    DIEP_DIRECTION             =          64 (&H40)
    DIEP_DURATION              =           1
    DIEP_ENVELOPE              =         128 (&H80)
    DIEP_GAIN                  =           4
    DIEP_NODOWNLOAD            = -2147483648 (&H80000000)
    DIEP_NORESTART             =  1073741824 (&H40000000)
    DIEP_SAMPLEPERIOD          =           2
    DIEP_START                 =   536870912 (&H20000000)
    DIEP_STARTDELAY            =         512 (&H200)
    DIEP_TRIGGERBUTTON         =           8
    DIEP_TRIGGERREPEATINTERVAL =          16 (&H10)
    DIEP_TYPESPECIFICPARAMS    =         256 (&H100)
End Enum

定数

DIEP_ALLPARAMS
未使用。
DIEP_AXES
未使用。
DIEP_DIRECTION
DIEFFECT の x および y メンバが有効である。または、方向パラメータがサポートされる。エフェクト パラメータを設定または要求している場合、DIEFFECT.lFlags の DIEFF_CARTESIAN か DIEFF_POLAR を指定することで、デカルト座標または極座標のどちらで方向を設定、または取得するかを指定できる。
DIEP_DURATION
DIEFFECT の lDuration メンバが有効である。または、エフェクトは方向の変更をサポートする。
DIEP_ENVELOPE
DIEFFECT の envelope メンバが有効である。または、エフェクトはエンベロープの適用をサポートする。
DIEP_GAIN
DIEFFECT の lGain メンバが有効である。または、エフェクトがゲインの適用をサポートする。
DIEP_NODOWNLOAD
パラメータの設定後、エフェクトをダウンロードしない。
DIEP_NORESTART
エフェクトの停止や再開を抑制してパラメータを変更する。
DIEP_SAMPLEPERIOD
DIEFFECT の lSamplePeriod メンバが有効である。
DIEP_START
エフェクトをすぐに開始する。
DIEP_STARTDELAY
DIEFFECT の lStartDelay メンバが有効である。または、エフェクトが開始遅延をサポートする。
DIEP_TRIGGERBUTTON
DIEFFECT の lTriggerButton メンバが有効である。または、エフェクトがトリガ ボタンをサポートする。
DIEP_TRIGGERREPEATINTERVAL
DIEFFECT の lTriggerRepeatInterval メンバが有効である。または、エフェクトがトリガの繰り返しをサポートする。
DIEP_TYPESPECIFICPARAMS
エフェクトは、アプリケーションが変更可能なタイプ固有のパラメータを持つ。この値は、すべての標準エフェクトと、アプリケーションによる変更が可能なパラメータを持つハードウェア固有のエフェクトに対して、DirectInputEnumEffects.GetStaticParams により返される。Microsoft® DirectX® for Microsoft Visual Basic® は、このフラグが設定されていない場合にのみハードウェア エフェクトをサポートする。


CONST_DIESFLAGS

DirectInputEffect.Start の flags パラメータに使用され、フォース フィードバック エフェクト再生の動作を制御する。

Enum CONST_DIESFLAGS
    DIES_NODOWNLOAD = -2147483648 (&H80000000)
    DIES_SOLO       =           1
End Enum

定数

DIES_NODOWNLOAD
エフェクトの自動ダウンロードを行わない。
DIES_SOLO
このエフェクトを再生する前に、ほかのすべてのエフェクトを停止する。このフラグを省略すると、エフェクトは、デバイス上で既に再生中のエフェクトと混合されることになる。


CONST_DIFEFFLAGS

DirectInputDevice8.CreateEffectFromFile メソッドの flags メンバに使用する。

Enum CONST_DIFEFFLAGS
    DIFEF_DEFAULT            =  0
    DIFEF_INCLUDENONSTANDARD =  1
    DIFEF_MODIFYIFNEEDED     = 16 (&H10)
End Enum

定数

DIFEF_DEFAULT
非標準のエフェクトを作成しない、または、エフェクト パラメータを変更する。
DIFEF_INCLUDENONSTANDARD
Microsoft® DirectInput® が事前定義していないエフェクト タイプを作成する。このフラグが設定されていない場合、このようなエフェクトが呼び出されると、メソッドは失敗する。
DIFEF_MODIFYIFNEEDED
現在のデバイスで再生できるように、記述されたエフェクトを必要に応じて変更するように DirectInput® に対して指示する。たとえば、2 つの軸に対して記述されたエフェクトは、デフォルトでは単一軸デバイスでは再生されない。このフラグを設定すると、単一軸でエフェクトが再生される。


CONST_DIGENRE

DIACTION 型の lSemantic メンバに使用され、仮想コントロールを指定するた。または、DIACTIONFORMAT 型の lGenre メンバに使用され、アクション マッピングのアプリケーション ジャンルを指定する。

この列挙の定数の詳細については、「アクション マッピング定数」の該当する項目を参照すること。

Enum CONST_DIGENRE
  DIAXIS_2DCONTROL_INOUT            = 587301379 (&H23018203)
  DIAXIS_2DCONTROL_LATERAL          = 587235841 (&H23008201)
  DIAXIS_2DCONTROL_MOVE             = 587268610 (&H23010202)
  DIAXIS_2DCONTROL_ROTATEZ          = 587350532 (&H23024204)
  DIAXIS_3DCONTROL_INOUT            = 604078595 (&H24018203)
  DIAXIS_3DCONTROL_LATERAL          = 604013057 (&H24008201)
  DIAXIS_3DCONTROL_MOVE             = 604045826 (&H24010202)
  DIAXIS_3DCONTROL_ROTATEX          = 604193284 (&H24034204)
  DIAXIS_3DCONTROL_ROTATEY          = 604160517 (&H2402C205)
  DIAXIS_3DCONTROL_ROTATEZ          = 604127750 (&H24024206)
  DIAXIS_ARCADEP_LATERAL            = 570458625 (&H22008201)
  DIAXIS_ARCADEP_MOVE               = 570491394 (&H22010202)
  DIAXIS_ARCADES_LATERAL            = 553681409 (&H21008201)
  DIAXIS_ARCADES_MOVE               = 553714178 (&H21010202)
  DIAXIS_BASEBALLB_LATERAL          = 251691521 (&H0F008201)
  DIAXIS_BASEBALLB_MOVE             = 251724290 (&H0F010202)
  DIAXIS_BASEBALLF_LATERAL          = 285245953 (&H11008201)
  DIAXIS_BASEBALLF_MOVE             = 285278722 (&H11010202)
  DIAXIS_BASEBALLP_LATERAL          = 268468737 (&H10008201)
  DIAXIS_BASEBALLP_MOVE             = 268501506 (&H10010202)
  DIAXIS_BBALLD_LATERAL             = 318800385 (&H13008201)
  DIAXIS_BBALLD_MOVE                = 318833154 (&H13010202)
  DIAXIS_BBALLO_LATERAL             = 302023169 (&H12008201)
  DIAXIS_BBALLO_MOVE                = 302055938 (&H12010202)
  DIAXIS_BIKINGM_BRAKE              = 470041091 (&H1C044203)
  DIAXIS_BIKINGM_PEDAL              = 469828098 (&H1C010202)
  DIAXIS_BIKINGM_TURN               = 469795329 (&H1C008201)
  DIAXIS_BROWSER_LATERAL            = 671121921 (&H28008201)
  DIAXIS_BROWSER_MOVE               = 671154690 (&H28010202)
  DIAXIS_BROWSER_VIEW               = 671187459 (&H28018203)
  DIAXIS_CADF_INOUT                 = 620855811 (&H25018203)
  DIAXIS_CADF_LATERAL               = 620790273 (&H25008201)
  DIAXIS_CADF_MOVE                  = 620823042 (&H25010202)
  DIAXIS_CADF_ROTATEX               = 620970500 (&H25034204)
  DIAXIS_CADF_ROTATEY               = 620937733 (&H2502C205)
  DIAXIS_CADF_ROTATEZ               = 620904966 (&H25024206)
  DIAXIS_CADM_INOUT                 = 637633027 (&H26018203)
  DIAXIS_CADM_LATERAL               = 637567489 (&H26008201)
  DIAXIS_CADM_MOVE                  = 637600258 (&H26010202)
  DIAXIS_CADM_ROTATEX               = 637747716 (&H26034204)
  DIAXIS_CADM_ROTATEY               = 637714949 (&H2602C205)
  DIAXIS_CADM_ROTATEZ               = 637682182 (&H26024206)
  DIAXIS_DRIVINGC_ACCEL_AND_BRAKE   =  33638916 (&H02014A04)
  DIAXIS_DRIVINGC_ACCELERATE        =  33788418 (&H02039202)
  DIAXIS_DRIVINGC_BRAKE             =  33821187 (&H02041203)
  DIAXIS_DRIVINGC_STEER             =  33589761 (&H03008A01)
  DIAXIS_DRIVINGR_ACCEL_AND_BRAKE   =  16861700 (&H01014A04)
  DIAXIS_DRIVINGR_ACCELERATE        =  17011202 (&H01039202)
  DIAXIS_DRIVINGR_BRAKE             =  17043971 (&H01041203)
  DIAXIS_DRIVINGR_STEER             =  16812545 (&H01008A01)
  DIAXIS_DRIVINGT_ACCEL_AND_BRAKE   =  50416133 (&H03014A05)
  DIAXIS_DRIVINGT_ACCELERATE        =  50565635 (&H03039203)
  DIAXIS_DRIVINGT_BARREL            =  50397698 (&H03010202)
  DIAXIS_DRIVINGT_BRAKE             =  50614788 (&H03045204)
  DIAXIS_DRIVINGT_STEER             =  50366977 (&H03008A01)
  DIAXIS_FIGHTINGH_LATERAL          = 134251009 (&H08008201)
  DIAXIS_FIGHTINGH_MOVE             = 134283778 (&H08010202)
  DIAXIS_FIGHTINGH_ROTATE           = 134365699 (&H08024203)
  DIAXIS_FISHING_LATERAL            = 234914305 (&H0E008201)
  DIAXIS_FISHING_MOVE               = 234947074 (&H0E010202)
  DIAXIS_FISHING_ROTATE             = 235028995 (&H0E024203)
  DIAXIS_FLYINGC_BANK               =  67144193 (&H04008A01)
  DIAXIS_FLYINGC_BRAKE              =  67398148 (&H04046A04)
  DIAXIS_FLYINGC_FLAPS              =  67459590 (&H04055A06)
  DIAXIS_FLYINGC_PITCH              =  67176962 (&H04010A02)
  DIAXIS_FLYINGC_RUDDER             =  67260933 (&H04025205)
  DIAXIS_FLYINGC_THROTTLE           =  67342851 (&H04039203)
  DIAXIS_FLYINGH_BANK               = 100698625 (&H06008A01)
  DIAXIS_FLYINGH_COLLECTIVE         = 100764163 (&H06018A03)
  DIAXIS_FLYINGH_PITCH              = 100731394 (&H06010A02)
  DIAXIS_FLYINGH_THROTTLE           = 100915717 (&H0603DA05)
  DIAXIS_FLYINGH_TORQUE             = 100817412 (&H06025A04)
  DIAXIS_FLYINGM_BANK               =  83921409 (&H05008A01)
  DIAXIS_FLYINGM_BRAKE              =  84173317 (&H05046205)
  DIAXIS_FLYINGM_FLAPS              =  84234758 (&H05055206)
  DIAXIS_FLYINGM_PITCH              =  83954178 (&H05010A02)
  DIAXIS_FLYINGM_RUDDER             =  84036100 (&H05024A04)
  DIAXIS_FLYINGM_THROTTLE           =  84120067 (&H05039203)
  DIAXIS_FOOTBALLD_LATERAL          = 385909249 (&H17008201)
  DIAXIS_FOOTBALLD_MOVE             = 385942018 (&H17010202)
  DIAXIS_FOOTBALLO_LATERAL          = 369132033 (&H16008201)
  DIAXIS_FOOTBALLO_MOVE             = 369164802 (&H16010202)
  DIAXIS_FOOTBALLQ_LATERAL          = 352354817 (&H15008201)
  DIAXIS_FOOTBALLQ_MOVE             = 352387586 (&H15010202)
  DIAXIS_FPS_LOOKUPDOWN             = 151093763 (&H09018203)
  DIAXIS_FPS_MOVE                   = 151060994 (&H09010202)
  DIAXIS_FPS_ROTATE                 = 151028225 (&H09008201)
  DIAXIS_FPS_SIDESTEP               = 151142916 (&H09024204)
  DIAXIS_GOLF_LATERAL               = 402686465 (&H18008201)
  DIAXIS_GOLF_MOVE                  = 402719234 (&H18010202)
  DIAXIS_HOCKEYD_LATERAL            = 436240897 (&H1A008201)
  DIAXIS_HOCKEYD_MOVE               = 436273666 (&H1A010202)
  DIAXIS_HOCKEYG_LATERAL            = 453018113 (&H1B008201)
  DIAXIS_HOCKEYG_MOVE               = 453050882 (&H1B010202)
  DIAXIS_HOCKEYO_LATERAL            = 419463681 (&H19008201)
  DIAXIS_HOCKEYO_MOVE               = 419496450 (&H19010202)
  DIAXIS_HUNTING_LATERAL            = 218137089 (&H0D008201)
  DIAXIS_HUNTING_MOVE               = 218169858 (&H0D010202)
  DIAXIS_HUNTING_ROTATE             = 218251779 (&H0D024203)
  DIAXIS_MECHA_ROTATE               = 687997443 (&H29020203)
  DIAXIS_MECHA_STEER                = 687899137 (&H29008201)
  DIAXIS_MECHA_THROTTLE             = 688095748 (&H29038204)
  DIAXIS_MECHA_TORSO                = 687931906 (&H29010202)
  DIAXIS_RACQUET_LATERAL            = 536904193 (&H20008201)
  DIAXIS_RACQUET_MOVE               = 536936962 (&H20010202)
  DIAXIS_REMOTE_SLIDER              = 654639617 (&H27050201)
  DIAXIS_REMOTE_SLIDER2             = 654656002 (&H27054202)
  DIAXIS_SKIING_SPEED               = 486605314 (&H1D010202)
  DIAXIS_SKIING_TURN                = 486572545 (&H1D008201)
  DIAXIS_SOCCERD_LATERAL            = 520126977 (&H1F008201)
  DIAXIS_SOCCERD_MOVE               = 520159746 (&H1F010202)
  DIAXIS_SOCCERO_BEND               = 503415299 (&H1E018203)
  DIAXIS_SOCCERO_LATERAL            = 503349761 (&H1E008201)
  DIAXIS_SOCCERO_MOVE               = 503382530 (&H1E010202)
  DIAXIS_SPACESIM_CLIMB             = 117555716 (&H0701C204)
  DIAXIS_SPACESIM_LATERAL           = 117473793 (&H07008201)
  DIAXIS_SPACESIM_MOVE              = 117506562 (&H07010202)
  DIAXIS_SPACESIM_ROTATE            = 117588485 (&H07024205)
  DIAXIS_SPACESIM_THROTTLE          = 117670403 (&H07038203)
  DIAXIS_STRATEGYR_LATERAL          = 184582657 (&H0B008201)
  DIAXIS_STRATEGYR_MOVE             = 184615426 (&H0B010202)
  DIAXIS_STRATEGYR_ROTATE           = 184697347 (&H0B024203)
  DIAXIS_STRATEGYT_LATERAL          = 201359873 (&H0C008201)
  DIAXIS_STRATEGYT_MOVE             = 201392642 (&H0C010202)
  DIAXIS_TPS_MOVE                   = 167838210 (&H0A010202)
  DIAXIS_TPS_STEP                   = 167821827 (&H0A00C203)
  DIAXIS_TPS_TURN                   = 167903745 (&H0A020201)
  DIBUTTON_2DCONTROL_DEVICE         = 587220222 (&H230044FE)
  DIBUTTON_2DCONTROL_DISPLAY        = 587219973 (&H23004405)
  DIBUTTON_2DCONTROL_MENU           = 587203837 (&H230004FD)
  DIBUTTON_2DCONTROL_PAUSE          = 587220220 (&H230044FC)
  DIBUTTON_2DCONTROL_SELECT         = 587203585 (&H23000401)
  DIBUTTON_2DCONTROL_SPECIAL        = 587203587 (&H23000403)
  DIBUTTON_2DCONTROL_SPECIAL1       = 587203586 (&H23000402)
  DIBUTTON_2DCONTROL_SPECIAL2       = 587203588 (&H23000404)
  DIBUTTON_3DCONTROL_DEVICE         = 603997438 (&H240044FE)
  DIBUTTON_3DCONTROL_DISPLAY        = 603997189 (&H24004405)
  DIBUTTON_3DCONTROL_MENU           = 603981053 (&H240004FD)
  DIBUTTON_3DCONTROL_PAUSE          = 603997436 (&H240044FC)
  DIBUTTON_3DCONTROL_SELECT         = 603980801 (&H24000401)
  DIBUTTON_3DCONTROL_SPECIAL        = 603980803 (&H24000403)
  DIBUTTON_3DCONTROL_SPECIAL1       = 603980802 (&H24000402)
  DIBUTTON_3DCONTROL_SPECIAL2       = 603980804 (&H24000404)
  DIBUTTON_ARCADEP_BACK_LINK        = 570508520 (&H220144E8)
  DIBUTTON_ARCADEP_CROUCH           = 570426371 (&H22000403)
  DIBUTTON_ARCADEP_DEVICE           = 570443006 (&H220044FE)
  DIBUTTON_ARCADEP_FIRE             = 570426370 (&H22000402)
  DIBUTTON_ARCADEP_FIRESECONDARY    = 570442758 (&H22004406)
  DIBUTTON_ARCADEP_FORWARD_LINK     = 570508512 (&H220144E0)
  DIBUTTON_ARCADEP_JUMP             = 570426369 (&H22000401)
  DIBUTTON_ARCADEP_LEFT_LINK        = 570475748 (&H2200C4E4)
  DIBUTTON_ARCADEP_MENU             = 570426621 (&H220004FD)
  DIBUTTON_ARCADEP_PAUSE            = 570443004 (&H220044FC)
  DIBUTTON_ARCADEP_RIGHT_LINK       = 570475756 (&H2200C4EC)
  DIBUTTON_ARCADEP_SELECT           = 570426373 (&H22000405)
  DIBUTTON_ARCADEP_SPECIAL          = 570426372 (&H22000404)
  DIBUTTON_ARCADEP_VIEW_DOWN_LINK   = 570934504 (&H2207C4E8)
  DIBUTTON_ARCADEP_VIEW_LEFT_LINK   = 570934500 (&H2207C4E4)
  DIBUTTON_ARCADEP_VIEW_RIGHT_LINK  = 570934508 (&H2207C4EC)
  DIBUTTON_ARCADEP_VIEW_UP_LINK     = 570934496 (&H2207C4E0)
  DIBUTTON_ARCADES_ATTACK           = 553649155 (&H21000403)
  DIBUTTON_ARCADES_BACK_LINK        = 553731304 (&H210144E8)
  DIBUTTON_ARCADES_CARRY            = 553649154 (&H21000402)
  DIBUTTON_ARCADES_DEVICE           = 553665790 (&H210044FE)
  DIBUTTON_ARCADES_FORWARD_LINK     = 553731296 (&H210144E0)
  DIBUTTON_ARCADES_LEFT_LINK        = 553698532 (&H2100C4E4)
  DIBUTTON_ARCADES_MENU             = 553649405 (&H210004FD)
  DIBUTTON_ARCADES_PAUSE            = 553665788 (&H210044FC)
  DIBUTTON_ARCADES_RIGHT_LINK       = 553698540 (&H2100C4EC)
  DIBUTTON_ARCADES_SELECT           = 553649157 (&H21000405)
  DIBUTTON_ARCADES_SPECIAL          = 553649156 (&H21000404)
  DIBUTTON_ARCADES_THROW            = 553649153 (&H21000401)
  DIBUTTON_ARCADES_VIEW_DOWN_LINK   = 554157288 (&H2107C4E8)
  DIBUTTON_ARCADES_VIEW_LEFT_LINK   = 554157284 (&H2107C4E4)
  DIBUTTON_ARCADES_VIEW_RIGHT_LINK  = 554157292 (&H2107C4EC)
  DIBUTTON_ARCADES_VIEW_UP_LINK     = 554157280 (&H2107C4E0)
  DIBUTTON_BASEBALLB_BACK_LINK      = 251741416 (&H0F0144E8)
  DIBUTTON_BASEBALLB_BOX            = 251675658 (&H0F00440A)
  DIBUTTON_BASEBALLB_BUNT           = 251659268 (&H0F000404)
  DIBUTTON_BASEBALLB_BURST          = 251659270 (&H0F000406)
  DIBUTTON_BASEBALLB_CONTACT        = 251659272 (&H0F000408)
  DIBUTTON_BASEBALLB_DEVICE         = 251675902 (&H0F0044FE)
  DIBUTTON_BASEBALLB_FORWARD_LINK   = 251741408 (&H0F0144E0)
  DIBUTTON_BASEBALLB_LEFT_LINK      = 251708644 (&H0F00C4E4)
  DIBUTTON_BASEBALLB_MENU           = 251659517 (&H0F0004FD)
  DIBUTTON_BASEBALLB_NORMAL         = 251659266 (&H0F000402)
  DIBUTTON_BASEBALLB_NOSTEAL        = 251675657 (&H0F004409)
  DIBUTTON_BASEBALLB_PAUSE          = 251675900 (&H0F0044FC)
  DIBUTTON_BASEBALLB_POWER          = 251659267 (&H0F000403)
  DIBUTTON_BASEBALLB_RIGHT_LINK     = 251708652 (&H0F00C4EC)
  DIBUTTON_BASEBALLB_SELECT         = 251659265 (&H0F000401)
  DIBUTTON_BASEBALLB_SLIDE          = 251659271 (&H0F000407)
  DIBUTTON_BASEBALLB_STEAL          = 251659269 (&H0F000405)
  DIBUTTON_BASEBALLF_AIM_LEFT_LINK  = 285263076 (&H1100C4E4)
  DIBUTTON_BASEBALLF_AIM_RIGHT_LINK = 285263084 (&H1100C4EC)
  DIBUTTON_BASEBALLF_BACK_LINK      = 285295848 (&H110144E8)
  DIBUTTON_BASEBALLF_BURST          = 285213700 (&H11000404)
  DIBUTTON_BASEBALLF_DEVICE         = 285230334 (&H110044FE)
  DIBUTTON_BASEBALLF_DIVE           = 285213702 (&H11000406)
  DIBUTTON_BASEBALLF_FORWARD_LINK   = 285295840 (&H110144E0)
  DIBUTTON_BASEBALLF_JUMP           = 285213701 (&H11000405)
  DIBUTTON_BASEBALLF_MENU           = 285213949 (&H110004FD)
  DIBUTTON_BASEBALLF_NEAREST        = 285213697 (&H11000401)
  DIBUTTON_BASEBALLF_PAUSE          = 285230332 (&H110044FC)
  DIBUTTON_BASEBALLF_SHIFTIN        = 285230087 (&H11004407)
  DIBUTTON_BASEBALLF_SHIFTOUT       = 285230088 (&H11004408)
  DIBUTTON_BASEBALLF_THROW1         = 285213698 (&H11000402)
  DIBUTTON_BASEBALLF_THROW2         = 285213699 (&H11000403)
  DIBUTTON_BASEBALLP_BACK_LINK      = 268518632 (&H100144E8)
  DIBUTTON_BASEBALLP_BASE           = 268436483 (&H10000403)
  DIBUTTON_BASEBALLP_DEVICE         = 268453118 (&H100044FE)
  DIBUTTON_BASEBALLP_FAKE           = 268436485 (&H10000405)
  DIBUTTON_BASEBALLP_FORWARD_LINK   = 268518624 (&H100144E0)
  DIBUTTON_BASEBALLP_LEFT_LINK      = 268485860 (&H1000C4E4)
  DIBUTTON_BASEBALLP_LOOK           = 268452871 (&H10004407)
  DIBUTTON_BASEBALLP_MENU           = 268436733 (&H100004FD)
  DIBUTTON_BASEBALLP_PAUSE          = 268453116 (&H100044FC)
  DIBUTTON_BASEBALLP_PITCH          = 268436482 (&H10000402)
  DIBUTTON_BASEBALLP_RIGHT_LINK     = 268485868 (&H1000C4EC)
  DIBUTTON_BASEBALLP_SELECT         = 268436481 (&H10000401)
  DIBUTTON_BASEBALLP_THROW          = 268436484 (&H10000404)
  DIBUTTON_BASEBALLP_WALK           = 268452870 (&H10004406)
  DIBUTTON_BBALLD_BACK_LINK         = 318850280 (&H130144E8)
  DIBUTTON_BBALLD_BURST             = 318768134 (&H13000406)
  DIBUTTON_BBALLD_DEVICE            = 318784766 (&H130044FE)
  DIBUTTON_BBALLD_FAKE              = 318768131 (&H13000403)
  DIBUTTON_BBALLD_FORWARD_LINK      = 318850272 (&H130144E0)
  DIBUTTON_BBALLD_JUMP              = 318768129 (&H13000401)
  DIBUTTON_BBALLD_LEFT_LINK         = 318817508 (&H1300C4E4)
  DIBUTTON_BBALLD_MENU              = 318768381 (&H130004FD)
  DIBUTTON_BBALLD_PAUSE             = 318784764 (&H130044FC)
  DIBUTTON_BBALLD_PLAY              = 318768135 (&H13000407)
  DIBUTTON_BBALLD_PLAYER            = 318768133 (&H13000405)
  DIBUTTON_BBALLD_RIGHT_LINK        = 318817516 (&H1300C4EC)
  DIBUTTON_BBALLD_SPECIAL           = 318768132 (&H13000404)
  DIBUTTON_BBALLD_STEAL             = 318768130 (&H13000402)
  DIBUTTON_BBALLD_SUBSTITUTE        = 318784521 (&H13004409)
  DIBUTTON_BBALLD_TIMEOUT           = 318784520 (&H13004408)
  DIBUTTON_BBALLO_BACK_LINK         = 302073064 (&H120144E8)
  DIBUTTON_BBALLO_BURST             = 301990919 (&H12000407)
  DIBUTTON_BBALLO_CALL              = 301990920 (&H12000408)
  DIBUTTON_BBALLO_DEVICE            = 302007550 (&H120044FE)
  DIBUTTON_BBALLO_DUNK              = 301990914 (&H12000402)
  DIBUTTON_BBALLO_FAKE              = 301990916 (&H12000404)
  DIBUTTON_BBALLO_FORWARD_LINK      = 302073056 (&H120144E0)
  DIBUTTON_BBALLO_JAB               = 302007307 (&H1200440B)
  DIBUTTON_BBALLO_LEFT_LINK         = 302040292 (&H1200C4E4)
  DIBUTTON_BBALLO_MENU              = 301991165 (&H120004FD)
  DIBUTTON_BBALLO_PASS              = 301990915 (&H12000403)
  DIBUTTON_BBALLO_PAUSE             = 302007548 (&H120044FC)
  DIBUTTON_BBALLO_PLAY              = 302007306 (&H1200440A)
  DIBUTTON_BBALLO_PLAYER            = 301990918 (&H12000406)
  DIBUTTON_BBALLO_POST              = 302007308 (&H1200440C)
  DIBUTTON_BBALLO_RIGHT_LINK        = 302040300 (&H1200C4EC)
  DIBUTTON_BBALLO_SCREEN            = 302007305 (&H12004409)
  DIBUTTON_BBALLO_SHOOT             = 301990913 (&H12000401)
  DIBUTTON_BBALLO_SPECIAL           = 301990917 (&H12000405)
  DIBUTTON_BBALLO_SUBSTITUTE        = 302007310 (&H1200440E)
  DIBUTTON_BBALLO_TIMEOUT           = 302007309 (&H1200440D)
  DIBUTTON_BIKINGM_BRAKE_BUTTON_LINK= 470041832 (&H1C0444E8)
  DIBUTTON_BIKINGM_CAMERA           = 469763074 (&H1C000402)
  DIBUTTON_BIKINGM_DEVICE           = 469779710 (&H1C0044FE)
  DIBUTTON_BIKINGM_FASTER_LINK      = 469845216 (&H1C0144E0)
  DIBUTTON_BIKINGM_JUMP             = 469763073 (&H1C000401)
  DIBUTTON_BIKINGM_LEFT_LINK        = 469812452 (&H1C00C4E4)
  DIBUTTON_BIKINGM_MENU             = 469763325 (&H1C0004FD)
  DIBUTTON_BIKINGM_PAUSE            = 469779708 (&H1C0044FC)
  DIBUTTON_BIKINGM_RIGHT_LINK       = 469812460 (&H1C00C4EC)
  DIBUTTON_BIKINGM_SELECT           = 469763076 (&H1C000404)
  DIBUTTON_BIKINGM_SLOWER_LINK      = 469845224 (&H1C0144E8)
  DIBUTTON_BIKINGM_SPECIAL1         = 469763075 (&H1C000403)
  DIBUTTON_BIKINGM_SPECIAL2         = 469763077 (&H1C000405)
  DIBUTTON_BIKINGM_ZOOM             = 469779462 (&H1C004406)
  DIBUTTON_BROWSER_DEVICE           = 671106302 (&H280044FE)
  DIBUTTON_BROWSER_FAVORITES        = 671106054 (&H28004406)
  DIBUTTON_BROWSER_HISTORY          = 671106057 (&H28004409)
  DIBUTTON_BROWSER_HOME             = 671106053 (&H28004405)
  DIBUTTON_BROWSER_MENU             = 671089917 (&H280004FD)
  DIBUTTON_BROWSER_NEXT             = 671106055 (&H28004407)
  DIBUTTON_BROWSER_PAUSE            = 671106300 (&H280044FC)
  DIBUTTON_BROWSER_PREVIOUS         = 671106056 (&H28004408)
  DIBUTTON_BROWSER_PRINT            = 671106058 (&H2800440A)
  DIBUTTON_BROWSER_REFRESH          = 671089666 (&H28000402)
  DIBUTTON_BROWSER_SEARCH           = 671106051 (&H28004403)
  DIBUTTON_BROWSER_SELECT           = 671089665 (&H28000401)
  DIBUTTON_BROWSER_STOP             = 671106052 (&H28004404)
  DIBUTTON_CADF_DEVICE              = 620774654 (&H250044FE)
  DIBUTTON_CADF_DISPLAY             = 620774405 (&H25004405)
  DIBUTTON_CADF_MENU                = 620758269 (&H250004FD)
  DIBUTTON_CADF_PAUSE               = 620774652 (&H250044FC)
  DIBUTTON_CADF_SELECT              = 620758017 (&H25000401)
  DIBUTTON_CADF_SPECIAL             = 620758019 (&H25000403)
  DIBUTTON_CADF_SPECIAL1            = 620758018 (&H25000402)
  DIBUTTON_CADF_SPECIAL2            = 620758020 (&H25000404)
  DIBUTTON_CADM_DEVICE              = 637551870 (&H260044FE)
  DIBUTTON_CADM_DISPLAY             = 637551621 (&H26004405)
  DIBUTTON_CADM_MENU                = 637535485 (&H260004FD)
  DIBUTTON_CADM_PAUSE               = 637551868 (&H260044FC)
  DIBUTTON_CADM_SELECT              = 637535233 (&H26000401)
  DIBUTTON_CADM_SPECIAL             = 637535235 (&H26000403)
  DIBUTTON_CADM_SPECIAL1            = 637535234 (&H26000402)
  DIBUTTON_CADM_SPECIAL2            = 637535236 (&H26000404)
  DIBUTTON_DRIVINGC_ACCELERATE_LINK =  33805536 (&H0203D4E0)
  DIBUTTON_DRIVINGC_AIDS            =  33571847 (&H02004407)
  DIBUTTON_DRIVINGC_BRAKE           =  33573896 (&H02004C08)
  DIBUTTON_DRIVINGC_DASHBOARD       =  33571846 (&H02004406)
  DIBUTTON_DRIVINGC_DEVICE          =  33572094 (&H020044FE)
  DIBUTTON_DRIVINGC_FIRE            =  33557505 (&H02000C01)
  DIBUTTON_DRIVINGC_FIRESECONDARY   =  33573897 (&H02004C09)
  DIBUTTON_DRIVINGC_GLANCE_LEFT_LINK = 34063588 (&H0207C4E4)
  DIBUTTON_DRIVINGC_GLANCE_RIGHT_LINK= 34063596 (&H0207C4EC)
  DIBUTTON_DRIVINGC_MENU            =  33555709 (&H020004FD)
  DIBUTTON_DRIVINGC_PAUSE           =  33572092 (&H020044FC)
  DIBUTTON_DRIVINGC_SHIFTDOWN       =  33573893 (&H02004C05)
  DIBUTTON_DRIVINGC_SHIFTUP         =  33573892 (&H02004C04)
  DIBUTTON_DRIVINGC_STEER_LEFT_LINK =  33606884 (&H0200CCE4)
  DIBUTTON_DRIVINGC_STEER_RIGHT_LINK = 33606892 (&H0200CCEC)
  DIBUTTON_DRIVINGC_TARGET          =  33557507 (&H02000C03)
  DIBUTTON_DRIVINGC_WEAPONS         =  33557506 (&H02000C02)
  DIBUTTON_DRIVINGR_ACCELERATE_LINK =  17028320 (&H0103D4E0)
  DIBUTTON_DRIVINGR_AIDS            =  16794630 (&H01004406)
  DIBUTTON_DRIVINGR_BOOST           =  16794632 (&H01004408)
  DIBUTTON_DRIVINGR_BRAKE           =  16796676 (&H01004C04)
  DIBUTTON_DRIVINGR_DASHBOARD       =  16794629 (&H01004405)
  DIBUTTON_DRIVINGR_DEVICE          =  16794878 (&H010044FE)
  DIBUTTON_DRIVINGR_GLANCE_LEFT_LINK = 17286372 (&H0107C4E4)
  DIBUTTON_DRIVINGR_GLANCE_RIGHT_LINK= 17286380 (&H0107C4EC)
  DIBUTTON_DRIVINGR_MAP             =  16794631 (&H01004407)
  DIBUTTON_DRIVINGR_MENU            =  16778493 (&H010004FD)
  DIBUTTON_DRIVINGR_PAUSE           =  16794876 (&H010044FC)
  DIBUTTON_DRIVINGR_PIT             =  16794633 (&H01004409)
  DIBUTTON_DRIVINGR_SHIFTDOWN       =  16780290 (&H01000C02)
  DIBUTTON_DRIVINGR_SHIFTUP         =  16780289 (&H01000C01)
  DIBUTTON_DRIVINGR_STEER_LEFT_LINK =  16829668 (&H0100CCE4)
  DIBUTTON_DRIVINGR_STEER_RIGHT_LINK = 16829676 (&H0100CCEC)
  DIBUTTON_DRIVINGR_VIEW            =  16784387 (&H01001C03)
  DIBUTTON_DRIVINGT_ACCELERATE_LINK =  50582752 (&H0303D4E0)
  DIBUTTON_DRIVINGT_BARREL_DOWN_LINK = 50414824 (&H030144E8)
  DIBUTTON_DRIVINGT_BARREL_UP_LINK  =  50414816 (&H030144E0)
  DIBUTTON_DRIVINGT_BRAKE           =  50351110 (&H03004C06)
  DIBUTTON_DRIVINGT_DASHBOARD       =  50355205 (&H03005C05)
  DIBUTTON_DRIVINGT_DEVICE          =  50349310 (&H030044FE)
  DIBUTTON_DRIVINGT_FIRE            =  50334721 (&H03000C01)
  DIBUTTON_DRIVINGT_FIRESECONDARY   =  50351111 (&H03004C07)
  DIBUTTON_DRIVINGT_GLANCE_LEFT_LINK = 50840804 (&H0307C4E4)
  DIBUTTON_DRIVINGT_GLANCE_RIGHT_LINK= 50840812 (&H0307C4EC)
  DIBUTTON_DRIVINGT_MENU            =  50332925 (&H030004FD)
  DIBUTTON_DRIVINGT_PAUSE           =  50349308 (&H030044FC)
  DIBUTTON_DRIVINGT_STEER_LEFT_LINK =  50384100 (&H0300CCE4)
  DIBUTTON_DRIVINGT_STEER_RIGHT_LINK = 50384108 (&H0300CCEC)
  DIBUTTON_DRIVINGT_TARGET          =  50334723 (&H03000C03)
  DIBUTTON_DRIVINGT_VIEW            =  50355204 (&H03005C04)
  DIBUTTON_DRIVINGT_WEAPONS         =  50334722 (&H03000C02)
  DIBUTTON_FIGHTINGH_BACKWARD_LINK  = 134300904 (&H080144E8)
  DIBUTTON_FIGHTINGH_BLOCK          = 134218755 (&H08000403)
  DIBUTTON_FIGHTINGH_CROUCH         = 134218756 (&H08000404)
  DIBUTTON_FIGHTINGH_DEVICE         = 134235390 (&H080044FE)
  DIBUTTON_FIGHTINGH_DISPLAY        = 134235145 (&H08004409)
  DIBUTTON_FIGHTINGH_DODGE          = 134235146 (&H0800440A)
  DIBUTTON_FIGHTINGH_FORWARD_LINK   = 134300896 (&H080144E0)
  DIBUTTON_FIGHTINGH_JUMP           = 134218757 (&H08000405)
  DIBUTTON_FIGHTINGH_KICK           = 134218754 (&H08000402)
  DIBUTTON_FIGHTINGH_LEFT_LINK      = 134268132 (&H0800C4E4)
  DIBUTTON_FIGHTINGH_MENU           = 134219005 (&H080004FD)
  DIBUTTON_FIGHTINGH_PAUSE          = 134235388 (&H080044FC)
  DIBUTTON_FIGHTINGH_PUNCH          = 134218753 (&H08000401)
  DIBUTTON_FIGHTINGH_RIGHT_LINK     = 134268140 (&H0800C4EC)
  DIBUTTON_FIGHTINGH_SELECT         = 134235144 (&H08004408)
  DIBUTTON_FIGHTINGH_SPECIAL1       = 134218758 (&H08000406)
  DIBUTTON_FIGHTINGH_SPECIAL2       = 134218759 (&H08000407)
  DIBUTTON_FISHING_BACK_LINK        = 234964200 (&H0E0144E8)
  DIBUTTON_FISHING_BAIT             = 234882052 (&H0E000404)
  DIBUTTON_FISHING_BINOCULAR        = 234882051 (&H0E000403)
  DIBUTTON_FISHING_CAST             = 234882049 (&H0E000401)
  DIBUTTON_FISHING_CROUCH           = 234898439 (&H0E004407)
  DIBUTTON_FISHING_DEVICE           = 234898686 (&H0E0044FE)
  DIBUTTON_FISHING_DISPLAY          = 234898438 (&H0E004406)
  DIBUTTON_FISHING_FORWARD_LINK     = 234964192 (&H0E0144E0)
  DIBUTTON_FISHING_JUMP             = 234898440 (&H0E004408)
  DIBUTTON_FISHING_LEFT_LINK        = 234931428 (&H0E00C4E4)
  DIBUTTON_FISHING_MAP              = 234882053 (&H0E000405)
  DIBUTTON_FISHING_MENU             = 234882301 (&H0E0004FD)
  DIBUTTON_FISHING_PAUSE            = 234898684 (&H0E0044FC)
  DIBUTTON_FISHING_RIGHT_LINK       = 234931436 (&H0E00C4EC)
  DIBUTTON_FISHING_ROTATE_LEFT_LINK = 235029732 (&H0E0244E4)
  DIBUTTON_FISHING_ROTATE_RIGHT_LINK= 235029740 (&H0E0244EC)
  DIBUTTON_FISHING_TYPE             = 234882050 (&H0E000402)
  DIBUTTON_FLYINGC_BRAKE_LINK       =  67398880 (&H04046CE0)
  DIBUTTON_FLYINGC_DEVICE           =  67126526 (&H040044FE)
  DIBUTTON_FLYINGC_DISPLAY          =  67118082 (&H04002402)
  DIBUTTON_FLYINGC_FASTER_LINK      =  67359968 (&H0403D4E0)
  DIBUTTON_FLYINGC_FLAPSDOWN        =  67134469 (&H04006405)
  DIBUTTON_FLYINGC_FLAPSUP          =  67134468 (&H04006404)
  DIBUTTON_FLYINGC_GEAR             =  67120131 (&H04002C03)
  DIBUTTON_FLYINGC_GLANCE_DOWN_LINK =  67618024 (&H0407C4E8)
  DIBUTTON_FLYINGC_GLANCE_LEFT_LINK =  67618020 (&H0407C4E4)
  DIBUTTON_FLYINGC_GLANCE_RIGHT_LINK = 67618028 (&H0407C4EC)
  DIBUTTON_FLYINGC_GLANCE_UP_LINK   =  67618016 (&H0407C4E0)
  DIBUTTON_FLYINGC_MENU             =  67110141 (&H040004FD)
  DIBUTTON_FLYINGC_PAUSE            =  67126524 (&H040044FC)
  DIBUTTON_FLYINGC_SLOWER_LINK      =  67359976 (&H0403D4E8)
  DIBUTTON_FLYINGC_VIEW             =  67118081 (&H04002401)
  DIBUTTON_FLYINGH_COUNTER          = 100684804 (&H06005404)
  DIBUTTON_FLYINGH_DEVICE           = 100680958 (&H060044FE)
  DIBUTTON_FLYINGH_FASTER_LINK      = 100916448 (&H0603DCE0)
  DIBUTTON_FLYINGH_FIRE             = 100668417 (&H06001401)
  DIBUTTON_FLYINGH_FIRESECONDARY    = 100682759 (&H06004C07)
  DIBUTTON_FLYINGH_GEAR             = 100688902 (&H06006406)
  DIBUTTON_FLYINGH_GLANCE_DOWN_LINK = 101172456 (&H0607C4E8)
  DIBUTTON_FLYINGH_GLANCE_LEFT_LINK = 101172452 (&H0607C4E4)
  DIBUTTON_FLYINGH_GLANCE_RIGHT_LINK= 101172460 (&H0607C4EC)
  DIBUTTON_FLYINGH_GLANCE_UP_LINK   = 101172448 (&H0607C4E0)
  DIBUTTON_FLYINGH_MENU             = 100664573 (&H060004FD)
  DIBUTTON_FLYINGH_PAUSE            = 100680956 (&H060044FC)
  DIBUTTON_FLYINGH_SLOWER_LINK      = 100916456 (&H0603DCE8)
  DIBUTTON_FLYINGH_TARGET           = 100668419 (&H06001403)
  DIBUTTON_FLYINGH_VIEW             = 100688901 (&H06006405)
  DIBUTTON_FLYINGH_WEAPONS          = 100668418 (&H06001402)
  DIBUTTON_FLYINGM_BRAKE_LINK       =  84174048 (&H050464E0)
  DIBUTTON_FLYINGM_COUNTER          =  83909636 (&H05005C04)
  DIBUTTON_FLYINGM_DEVICE           =  83903742 (&H050044FE)
  DIBUTTON_FLYINGM_DISPLAY          =  83911686 (&H05006406)
  DIBUTTON_FLYINGM_FASTER_LINK      =  84137184 (&H0503D4E0)
  DIBUTTON_FLYINGM_FIRE             =  83889153 (&H05000C01)
  DIBUTTON_FLYINGM_FIRESECONDARY    =  83905546 (&H05004C09)
  DIBUTTON_FLYINGM_FLAPSDOWN        =  83907592 (&H05005408)
  DIBUTTON_FLYINGM_FLAPSUP          =  83907591 (&H05005407)
  DIBUTTON_FLYINGM_GEAR             =  83911689 (&H0500640A)
  DIBUTTON_FLYINGM_GLANCE_DOWN_LINK =  84395240 (&H0507C4E8)
  DIBUTTON_FLYINGM_GLANCE_LEFT_LINK =  84395236 (&H0507C4E4)
  DIBUTTON_FLYINGM_GLANCE_RIGHT_LINK = 84395244 (&H0507C4EC)
  DIBUTTON_FLYINGM_GLANCE_UP_LINK   =  84395232 (&H0507C4E0)
  DIBUTTON_FLYINGM_MENU             =  83887357 (&H050004FD)
  DIBUTTON_FLYINGM_PAUSE            =  83903740 (&H050044FC)
  DIBUTTON_FLYINGM_SLOWER_LINK      =  84137192 (&H0503D4E8)
  DIBUTTON_FLYINGM_TARGET           =  83889155 (&H05000C03)
  DIBUTTON_FLYINGM_VIEW             =  83911685 (&H05006405)
  DIBUTTON_FLYINGM_WEAPONS          =  83889154 (&H05000C02)
  DIBUTTON_FOOTBALLD_AUDIBLE        = 385893387 (&H1700440B)
  DIBUTTON_FOOTBALLD_BACK_LINK      = 385959144 (&H170144E8)
  DIBUTTON_FOOTBALLD_BULLRUSH       = 385893385 (&H17004409)
  DIBUTTON_FOOTBALLD_DEVICE         = 385893630 (&H170044FE)
  DIBUTTON_FOOTBALLD_FAKE           = 385876997 (&H17000405)
  DIBUTTON_FOOTBALLD_FORWARD_LINK   = 385959136 (&H170144E0)
  DIBUTTON_FOOTBALLD_JUMP           = 385876995 (&H17000403)
  DIBUTTON_FOOTBALLD_LEFT_LINK      = 385926372 (&H1700C4E4)
  DIBUTTON_FOOTBALLD_MENU           = 385877245 (&H170004FD)
  DIBUTTON_FOOTBALLD_PAUSE          = 385893628 (&H170044FC)
  DIBUTTON_FOOTBALLD_PLAY           = 385876993 (&H17000401)
  DIBUTTON_FOOTBALLD_RIGHT_LINK     = 385926380 (&H1700C4EC)
  DIBUTTON_FOOTBALLD_RIP            = 385893386 (&H1700440A)
  DIBUTTON_FOOTBALLD_SELECT         = 385876994 (&H17000402)
  DIBUTTON_FOOTBALLD_SPIN           = 385893383 (&H17004407)
  DIBUTTON_FOOTBALLD_SUBSTITUTE     = 385893389 (&H1700440D)
  DIBUTTON_FOOTBALLD_SUPERTACKLE    = 385876998 (&H17000406)
  DIBUTTON_FOOTBALLD_SWIM           = 385893384 (&H17004408)
  DIBUTTON_FOOTBALLD_TACKLE         = 385876996 (&H17000404)
  DIBUTTON_FOOTBALLD_ZOOM           = 385893388 (&H1700440C)
  DIBUTTON_FOOTBALLO_BACK_LINK      = 369181928 (&H160144E8)
  DIBUTTON_FOOTBALLO_DEVICE         = 369116414 (&H160044FE)
  DIBUTTON_FOOTBALLO_DIVE           = 369116169 (&H16004409)
  DIBUTTON_FOOTBALLO_FORWARD_LINK   = 369181920 (&H160144E0)
  DIBUTTON_FOOTBALLO_JUKE           = 369116166 (&H16004406)
  DIBUTTON_FOOTBALLO_JUMP           = 369099777 (&H16000401)
  DIBUTTON_FOOTBALLO_LEFT_LINK      = 369149156 (&H1600C4E4)
  DIBUTTON_FOOTBALLO_LEFTARM        = 369099778 (&H16000402)
  DIBUTTON_FOOTBALLO_MENU           = 369100029 (&H160004FD)
  DIBUTTON_FOOTBALLO_PAUSE          = 369116412 (&H160044FC)
  DIBUTTON_FOOTBALLO_RIGHT_LINK     = 369149164 (&H1600C4EC)
  DIBUTTON_FOOTBALLO_RIGHTARM       = 369099779 (&H16000403)
  DIBUTTON_FOOTBALLO_SHOULDER       = 369116167 (&H16004407)
  DIBUTTON_FOOTBALLO_SPIN           = 369099781 (&H16000405)
  DIBUTTON_FOOTBALLO_SUBSTITUTE     = 369116171 (&H1600440B)
  DIBUTTON_FOOTBALLO_THROW          = 369099780 (&H16000404)
  DIBUTTON_FOOTBALLO_TURBO          = 369116168 (&H16004408)
  DIBUTTON_FOOTBALLO_ZOOM           = 369116170 (&H1600440A)
  DIBUTTON_FOOTBALLP_DEVICE         = 335561982 (&H140044FE)
  DIBUTTON_FOOTBALLP_HELP           = 335545347 (&H14000403)
  DIBUTTON_FOOTBALLP_MENU           = 335545597 (&H140004FD)
  DIBUTTON_FOOTBALLP_PAUSE          = 335561980 (&H140044FC)
  DIBUTTON_FOOTBALLP_PLAY           = 335545345 (&H14000401)
  DIBUTTON_FOOTBALLP_SELECT         = 335545346 (&H14000402)
  DIBUTTON_FOOTBALLQ_AUDIBLE        = 352338953 (&H15004409)
  DIBUTTON_FOOTBALLQ_BACK_LINK      = 352404712 (&H150144E8)
  DIBUTTON_FOOTBALLQ_DEVICE         = 352339198 (&H150044FE)
  DIBUTTON_FOOTBALLQ_FAKE           = 352322566 (&H15000406)
  DIBUTTON_FOOTBALLQ_FAKESNAP       = 352338951 (&H15004407)
  DIBUTTON_FOOTBALLQ_FORWARD_LINK   = 352404704 (&H150144E0)
  DIBUTTON_FOOTBALLQ_JUMP           = 352322563 (&H15000403)
  DIBUTTON_FOOTBALLQ_LEFT_LINK      = 352371940 (&H1500C4E4)
  DIBUTTON_FOOTBALLQ_MENU           = 352322813 (&H150004FD)
  DIBUTTON_FOOTBALLQ_MOTION         = 352338952 (&H15004408)
  DIBUTTON_FOOTBALLQ_PASS           = 352322565 (&H15000405)
  DIBUTTON_FOOTBALLQ_PAUSE          = 352339196 (&H150044FC)
  DIBUTTON_FOOTBALLQ_RIGHT_LINK     = 352371948 (&H1500C4EC)
  DIBUTTON_FOOTBALLQ_SELECT         = 352322561 (&H15000401)
  DIBUTTON_FOOTBALLQ_SLIDE          = 352322564 (&H15000404)
  DIBUTTON_FOOTBALLQ_SNAP           = 352322562 (&H15000402)
  DIBUTTON_FPS_APPLY                = 150995971 (&H09000403)
  DIBUTTON_FPS_BACKWARD_LINK        = 151078120 (&H090144E8)
  DIBUTTON_FPS_CROUCH               = 150995973 (&H09000405)
  DIBUTTON_FPS_DEVICE               = 151012606 (&H090044FE)
  DIBUTTON_FPS_DISPLAY              = 151012360 (&H09004408)
  DIBUTTON_FPS_DODGE                = 151012361 (&H09004409)
  DIBUTTON_FPS_FIRE                 = 150995969 (&H09000401)
  DIBUTTON_FPS_FIRESECONDARY        = 151012364 (&H0900440C)
  DIBUTTON_FPS_FORWARD_LINK         = 151078112 (&H090144E0)
  DIBUTTON_FPS_GLANCE_DOWN_LINK     = 151110888 (&H0901C4E8)
  DIBUTTON_FPS_GLANCE_UP_LINK       = 151110880 (&H0901C4E0)
  DIBUTTON_FPS_GLANCEL              = 151012362 (&H0900440A)
  DIBUTTON_FPS_GLANCER              = 151012363 (&H0900440B)
  DIBUTTON_FPS_JUMP                 = 150995974 (&H09000406)
  DIBUTTON_FPS_MENU                 = 150996221 (&H090004FD)
  DIBUTTON_FPS_PAUSE                = 151012604 (&H090044FC)
  DIBUTTON_FPS_ROTATE_LEFT_LINK     = 151045348 (&H0900C4E4)
  DIBUTTON_FPS_ROTATE_RIGHT_LINK    = 151045356 (&H0900C4EC)
  DIBUTTON_FPS_SELECT               = 150995972 (&H09000404)
  DIBUTTON_FPS_STRAFE               = 150995975 (&H09000407)
  DIBUTTON_FPS_WEAPONS              = 150995970 (&H09000402)
  DIBUTTON_GOLF_BACK_LINK           = 402736360 (&H180144E8)
  DIBUTTON_GOLF_DEVICE              = 402670846 (&H180044FE)
  DIBUTTON_GOLF_DOWN                = 402654212 (&H18000404)
  DIBUTTON_GOLF_FLYBY               = 402654214 (&H18000406)
  DIBUTTON_GOLF_FORWARD_LINK        = 402736352 (&H180144E0)
  DIBUTTON_GOLF_LEFT_LINK           = 402703588 (&H1800C4E4)
  DIBUTTON_GOLF_MENU                = 402654461 (&H180004FD)
  DIBUTTON_GOLF_PAUSE               = 402670844 (&H180044FC)
  DIBUTTON_GOLF_RIGHT_LINK          = 402703596 (&H1800C4EC)
  DIBUTTON_GOLF_SELECT              = 402654210 (&H18000402)
  DIBUTTON_GOLF_SUBSTITUTE          = 402670601 (&H18004409)
  DIBUTTON_GOLF_SWING               = 402654209 (&H18000401)
  DIBUTTON_GOLF_TERRAIN             = 402654213 (&H18000405)
  DIBUTTON_GOLF_TIMEOUT             = 402670600 (&H18004408)
  DIBUTTON_GOLF_UP                  = 402654211 (&H18000403)
  DIBUTTON_GOLF_ZOOM                = 402670599 (&H18004407)
  DIBUTTON_HOCKEYD_BACK_LINK        = 436290792 (&H1A0144E8)
  DIBUTTON_HOCKEYD_BLOCK            = 436208644 (&H1A000404)
  DIBUTTON_HOCKEYD_BURST            = 436208643 (&H1A000403)
  DIBUTTON_HOCKEYD_DEVICE           = 436225278 (&H1A0044FE)
  DIBUTTON_HOCKEYD_FAKE             = 436208645 (&H1A000405)
  DIBUTTON_HOCKEYD_FORWARD_LINK     = 436290784 (&H1A0144E0)
  DIBUTTON_HOCKEYD_LEFT_LINK        = 436258020 (&H1A00C4E4)
  DIBUTTON_HOCKEYD_MENU             = 436208893 (&H1A0004FD)
  DIBUTTON_HOCKEYD_PAUSE            = 436225276 (&H1A0044FC)
  DIBUTTON_HOCKEYD_PLAYER           = 436208641 (&H1A000401)
  DIBUTTON_HOCKEYD_RIGHT_LINK       = 436258028 (&H1A00C4EC)
  DIBUTTON_HOCKEYD_STEAL            = 436208642 (&H1A000402)
  DIBUTTON_HOCKEYD_STRATEGY         = 436225031 (&H1A004407)
  DIBUTTON_HOCKEYD_SUBSTITUTE       = 436225033 (&H1A004409)
  DIBUTTON_HOCKEYD_TIMEOUT          = 436225032 (&H1A004408)
  DIBUTTON_HOCKEYD_ZOOM             = 436225030 (&H1A004406)
  DIBUTTON_HOCKEYG_BACK_LINK        = 453068008 (&H1B0144E8)
  DIBUTTON_HOCKEYG_BLOCK            = 452985860 (&H1B000404)
  DIBUTTON_HOCKEYG_DEVICE           = 453002494 (&H1B0044FE)
  DIBUTTON_HOCKEYG_FORWARD_LINK     = 453068000 (&H1B0144E0)
  DIBUTTON_HOCKEYG_LEFT_LINK        = 453035236 (&H1B00C4E4)
  DIBUTTON_HOCKEYG_MENU             = 452986109 (&H1B0004FD)
  DIBUTTON_HOCKEYG_PASS             = 452985857 (&H1B000401)
  DIBUTTON_HOCKEYG_PAUSE            = 453002492 (&H1B0044FC)
  DIBUTTON_HOCKEYG_POKE             = 452985858 (&H1B000402)
  DIBUTTON_HOCKEYG_RIGHT_LINK       = 453035244 (&H1B00C4EC)
  DIBUTTON_HOCKEYG_STEAL            = 452985859 (&H1B000403)
  DIBUTTON_HOCKEYG_STRATEGY         = 453002246 (&H1B004406)
  DIBUTTON_HOCKEYG_SUBSTITUTE       = 453002248 (&H1B004408)
  DIBUTTON_HOCKEYG_TIMEOUT          = 453002247 (&H1B004407)
  DIBUTTON_HOCKEYG_ZOOM             = 453002245 (&H1B004405)
  DIBUTTON_HOCKEYO_BACK_LINK        = 419513576 (&H190144E8)
  DIBUTTON_HOCKEYO_BURST            = 419431427 (&H19000403)
  DIBUTTON_HOCKEYO_DEVICE           = 419448062 (&H190044FE)
  DIBUTTON_HOCKEYO_FAKE             = 419431429 (&H19000405)
  DIBUTTON_HOCKEYO_FORWARD_LINK     = 419513568 (&H190144E0)
  DIBUTTON_HOCKEYO_LEFT_LINK        = 419480804 (&H1900C4E4)
  DIBUTTON_HOCKEYO_MENU             = 419431677 (&H190004FD)
  DIBUTTON_HOCKEYO_PASS             = 419431426 (&H19000402)
  DIBUTTON_HOCKEYO_PAUSE            = 419448060 (&H190044FC)
  DIBUTTON_HOCKEYO_RIGHT_LINK       = 419480812 (&H1900C4EC)
  DIBUTTON_HOCKEYO_SHOOT            = 419431425 (&H19000401)
  DIBUTTON_HOCKEYO_SPECIAL          = 419431428 (&H19000404)
  DIBUTTON_HOCKEYO_STRATEGY         = 419447815 (&H19004407)
  DIBUTTON_HOCKEYO_SUBSTITUTE       = 419447817 (&H19004409)
  DIBUTTON_HOCKEYO_TIMEOUT          = 419447816 (&H19004408)
  DIBUTTON_HOCKEYO_ZOOM             = 419447814 (&H19004406)
  DIBUTTON_HUNTING_AIM              = 218104834 (&H0D000402)
  DIBUTTON_HUNTING_BACK_LINK        = 218186984 (&H0D0144E8)
  DIBUTTON_HUNTING_BINOCULAR        = 218104836 (&H0D000404)
  DIBUTTON_HUNTING_CALL             = 218104837 (&H0D000405)
  DIBUTTON_HUNTING_CROUCH           = 218121225 (&H0D004409)
  DIBUTTON_HUNTING_DEVICE           = 218121470 (&H0D0044FE)
  DIBUTTON_HUNTING_DISPLAY          = 218121224 (&H0D004408)
  DIBUTTON_HUNTING_FIRE             = 218104833 (&H0D000401)
  DIBUTTON_HUNTING_FIRESECONDARY    = 218121227 (&H0D00440B)
  DIBUTTON_HUNTING_FORWARD_LINK     = 218186976 (&H0D0144E0)
  DIBUTTON_HUNTING_JUMP             = 218121226 (&H0D00440A)
  DIBUTTON_HUNTING_LEFT_LINK        = 218154212 (&H0D00C4E4)
  DIBUTTON_HUNTING_MAP              = 218104838 (&H0D000406)
  DIBUTTON_HUNTING_MENU             = 218105085 (&H0D0004FD)
  DIBUTTON_HUNTING_PAUSE            = 218121468 (&H0D0044FC)
  DIBUTTON_HUNTING_RIGHT_LINK       = 218154220 (&H0D00C4EC)
  DIBUTTON_HUNTING_ROTATE_LEFT_LINK = 218252516 (&H0D0244E4)
  DIBUTTON_HUNTING_ROTATE_RIGHT_LINK= 218252524 (&H0D0244EC)
  DIBUTTON_HUNTING_SPECIAL          = 218104839 (&H0D000407)
  DIBUTTON_HUNTING_WEAPON           = 218104835 (&H0D000403)
  DIBUTTON_MECHA_BACK_LINK          = 687949032 (&H290144E8)
  DIBUTTON_MECHA_CENTER             = 687883271 (&H29004407)
  DIBUTTON_MECHA_DEVICE             = 687883518 (&H290044FE)
  DIBUTTON_MECHA_FASTER_LINK        = 688112864 (&H2903C4E0)
  DIBUTTON_MECHA_FIRE               = 687866881 (&H29000401)
  DIBUTTON_MECHA_FIRESECONDARY      = 687883273 (&H29004409)
  DIBUTTON_MECHA_FORWARD_LINK       = 687949024 (&H290144E0)
  DIBUTTON_MECHA_JUMP               = 687866886 (&H29000406)
  DIBUTTON_MECHA_LEFT_LINK          = 687916260 (&H2900C4E4)
  DIBUTTON_MECHA_MENU               = 687867133 (&H290004FD)
  DIBUTTON_MECHA_PAUSE              = 687883516 (&H290044FC)
  DIBUTTON_MECHA_REVERSE            = 687866884 (&H29000404)
  DIBUTTON_MECHA_RIGHT_LINK         = 687916268 (&H2900C4EC)
  DIBUTTON_MECHA_ROTATE_LEFT_LINK   = 688014564 (&H290244E4)
  DIBUTTON_MECHA_ROTATE_RIGHT_LINK  = 688014572 (&H290244EC)
  DIBUTTON_MECHA_SLOWER_LINK        = 688112872 (&H2903C4E8)
  DIBUTTON_MECHA_TARGET             = 687866883 (&H29000403)
  DIBUTTON_MECHA_VIEW               = 687883272 (&H29004408)
  DIBUTTON_MECHA_WEAPONS            = 687866882 (&H29000402)
  DIBUTTON_MECHA_ZOOM               = 687866885 (&H29000405)
  DIBUTTON_RACQUET_BACK_LINK        = 536954088 (&H200144E8)
  DIBUTTON_RACQUET_BACKSWING        = 536871938 (&H20000402)
  DIBUTTON_RACQUET_DEVICE           = 536888574 (&H200044FE)
  DIBUTTON_RACQUET_FORWARD_LINK     = 536954080 (&H200144E0)
  DIBUTTON_RACQUET_LEFT_LINK        = 536921316 (&H2000C4E4)
  DIBUTTON_RACQUET_MENU             = 536872189 (&H200004FD)
  DIBUTTON_RACQUET_PAUSE            = 536888572 (&H200044FC)
  DIBUTTON_RACQUET_RIGHT_LINK       = 536921324 (&H2000C4EC)
  DIBUTTON_RACQUET_SELECT           = 536871941 (&H20000405)
  DIBUTTON_RACQUET_SMASH            = 536871939 (&H20000403)
  DIBUTTON_RACQUET_SPECIAL          = 536871940 (&H20000404)
  DIBUTTON_RACQUET_SUBSTITUTE       = 536888327 (&H20004407)
  DIBUTTON_RACQUET_SWING            = 536871937 (&H20000401)
  DIBUTTON_RACQUET_TIMEOUT          = 536888326 (&H20004406)
  DIBUTTON_REMOTE_ADJUST            = 654334990 (&H27005C0E)
  DIBUTTON_REMOTE_CABLE             = 654334985 (&H27005C09)
  DIBUTTON_REMOTE_CD                = 654334986 (&H27005C0A)
  DIBUTTON_REMOTE_CHANGE            = 654320646 (&H27002406)
  DIBUTTON_REMOTE_CUE               = 654320644 (&H27002404)
  DIBUTTON_REMOTE_DEVICE            = 654329086 (&H270044FE)
  DIBUTTON_REMOTE_DIGIT0            = 654332943 (&H2700540F)
  DIBUTTON_REMOTE_DIGIT1            = 654332944 (&H27005410)
  DIBUTTON_REMOTE_DIGIT2            = 654332945 (&H27005411)
  DIBUTTON_REMOTE_DIGIT3            = 654332946 (&H27005412)
  DIBUTTON_REMOTE_DIGIT4            = 654332947 (&H27005413)
  DIBUTTON_REMOTE_DIGIT5            = 654332948 (&H27005414)
  DIBUTTON_REMOTE_DIGIT6            = 654332949 (&H27005415)
  DIBUTTON_REMOTE_DIGIT7            = 654332950 (&H27005416)
  DIBUTTON_REMOTE_DIGIT8            = 654332951 (&H27005417)
  DIBUTTON_REMOTE_DIGIT9            = 654332952 (&H27005418)
  DIBUTTON_REMOTE_DVD               = 654334989 (&H27005C0D)
  DIBUTTON_REMOTE_MENU              = 654312701 (&H270004FD)
  DIBUTTON_REMOTE_MUTE              = 654312449 (&H27000401)
  DIBUTTON_REMOTE_PAUSE             = 654329084 (&H270044FC)
  DIBUTTON_REMOTE_PLAY              = 654320643 (&H27002403)
  DIBUTTON_REMOTE_RECORD            = 654320647 (&H27002407)
  DIBUTTON_REMOTE_REVIEW            = 654320645 (&H27002405)
  DIBUTTON_REMOTE_SELECT            = 654312450 (&H27000402)
  DIBUTTON_REMOTE_TUNER             = 654334988 (&H27005C0C)
  DIBUTTON_REMOTE_TV                = 654334984 (&H27005C08)
  DIBUTTON_REMOTE_VCR               = 654334987 (&H27005C0B)
  DIBUTTON_SKIING_CAMERA            = 486540291 (&H1D000403)
  DIBUTTON_SKIING_CROUCH            = 486540290 (&H1D000402)
  DIBUTTON_SKIING_DEVICE            = 486556926 (&H1D0044FE)
  DIBUTTON_SKIING_FASTER_LINK       = 486622432 (&H1D0144E0)
  DIBUTTON_SKIING_JUMP              = 486540289 (&H1D000401)
  DIBUTTON_SKIING_LEFT_LINK         = 486589668 (&H1D00C4E4)
  DIBUTTON_SKIING_MENU              = 486540541 (&H1D0004FD)
  DIBUTTON_SKIING_PAUSE             = 486556924 (&H1D0044FC)
  DIBUTTON_SKIING_RIGHT_LINK        = 486589676 (&H1D00C4EC)
  DIBUTTON_SKIING_SELECT            = 486540293 (&H1D000405)
  DIBUTTON_SKIING_SLOWER_LINK       = 486622440 (&H1D0144E8)
  DIBUTTON_SKIING_SPECIAL1          = 486540292 (&H1D000404)
  DIBUTTON_SKIING_SPECIAL2          = 486540294 (&H1D000406)
  DIBUTTON_SKIING_ZOOM              = 486556679 (&H1D004407)
  DIBUTTON_SOCCERD_BACK_LINK        = 520176872 (&H1F0144E8)
  DIBUTTON_SOCCERD_BLOCK            = 520094721 (&H1F000401)
  DIBUTTON_SOCCERD_CLEAR            = 520111114 (&H1F00440A)
  DIBUTTON_SOCCERD_DEVICE           = 520111358 (&H1F0044FE)
  DIBUTTON_SOCCERD_FAKE             = 520094723 (&H1F000403)
  DIBUTTON_SOCCERD_FORWARD_LINK     = 520176864 (&H1F0144E0)
  DIBUTTON_SOCCERD_FOUL             = 520111112 (&H1F004408)
  DIBUTTON_SOCCERD_GOALIECHARGE     = 520111115 (&H1F00440B)
  DIBUTTON_SOCCERD_HEAD             = 520111113 (&H1F004409)
  DIBUTTON_SOCCERD_LEFT_LINK        = 520144100 (&H1F00C4E4)
  DIBUTTON_SOCCERD_MENU             = 520094973 (&H1F0004FD)
  DIBUTTON_SOCCERD_PAUSE            = 520111356 (&H1F0044FC)
  DIBUTTON_SOCCERD_PLAYER           = 520094724 (&H1F000404)
  DIBUTTON_SOCCERD_RIGHT_LINK       = 520144108 (&H1F00C4EC)
  DIBUTTON_SOCCERD_SELECT           = 520094726 (&H1F000406)
  DIBUTTON_SOCCERD_SLIDE            = 520094727 (&H1F000407)
  DIBUTTON_SOCCERD_SPECIAL          = 520094725 (&H1F000405)
  DIBUTTON_SOCCERD_STEAL            = 520094722 (&H1F000402)
  DIBUTTON_SOCCERD_SUBSTITUTE       = 520111116 (&H1F00440C)
  DIBUTTON_SOCCERO_BACK_LINK        = 503399656 (&H1E0144E8)
  DIBUTTON_SOCCERO_CONTROL          = 503333900 (&H1E00440C)
  DIBUTTON_SOCCERO_DEVICE           = 503334142 (&H1E0044FE)
  DIBUTTON_SOCCERO_FAKE             = 503317507 (&H1E000403)
  DIBUTTON_SOCCERO_FORWARD_LINK     = 503399648 (&H1E0144E0)
  DIBUTTON_SOCCERO_HEAD             = 503333901 (&H1E00440D)
  DIBUTTON_SOCCERO_LEFT_LINK        = 503366884 (&H1E00C4E4)
  DIBUTTON_SOCCERO_MENU             = 503317757 (&H1E0004FD)
  DIBUTTON_SOCCERO_PASS             = 503317506 (&H1E000402)
  DIBUTTON_SOCCERO_PASSTHRU         = 503333898 (&H1E00440A)
  DIBUTTON_SOCCERO_PAUSE            = 503334140 (&H1E0044FC)
  DIBUTTON_SOCCERO_PLAYER           = 503317508 (&H1E000404)
  DIBUTTON_SOCCERO_RIGHT_LINK       = 503366892 (&H1E00C4EC)
  DIBUTTON_SOCCERO_SELECT           = 503317510 (&H1E000406)
  DIBUTTON_SOCCERO_SHOOT            = 503317505 (&H1E000401)
  DIBUTTON_SOCCERO_SHOOTHIGH        = 503333897 (&H1E004409)
  DIBUTTON_SOCCERO_SHOOTLOW         = 503333896 (&H1E004408)
  DIBUTTON_SOCCERO_SPECIAL1         = 503317509 (&H1E000405)
  DIBUTTON_SOCCERO_SPRINT           = 503333899 (&H1E00440B)
  DIBUTTON_SOCCERO_SUBSTITUTE       = 503333895 (&H1E004407)
  DIBUTTON_SPACESIM_BACKWARD_LINK   = 117523688 (&H070144E8)
  DIBUTTON_SPACESIM_DEVICE          = 117458174 (&H070044FE)
  DIBUTTON_SPACESIM_DISPLAY         = 117457925 (&H07004405)
  DIBUTTON_SPACESIM_FASTER_LINK     = 117687520 (&H0703C4E0)
  DIBUTTON_SPACESIM_FIRE            = 117441537 (&H07000401)
  DIBUTTON_SPACESIM_FIRESECONDARY   = 117457929 (&H07004409)
  DIBUTTON_SPACESIM_FORWARD_LINK    = 117523680 (&H070144E0)
  DIBUTTON_SPACESIM_GEAR            = 117457928 (&H07004408)
  DIBUTTON_SPACESIM_GLANCE_DOWN_LINK= 117949672 (&H0707C4E8)
  DIBUTTON_SPACESIM_GLANCE_LEFT_LINK= 117949668 (&H0707C4E4)
  DIBUTTON_SPACESIM_GLANCE_RIGHT_LINK=117949676 (&H0707C4EC)
  DIBUTTON_SPACESIM_GLANCE_UP_LINK  = 117949664 (&H0707C4E0)
  DIBUTTON_SPACESIM_LEFT_LINK       = 117490916 (&H0700C4E4)
  DIBUTTON_SPACESIM_LOWER           = 117457927 (&H07004407)
  DIBUTTON_SPACESIM_MENU            = 117441789 (&H070004FD)
  DIBUTTON_SPACESIM_PAUSE           = 117458172 (&H070044FC)
  DIBUTTON_SPACESIM_RAISE           = 117457926 (&H07004406)
  DIBUTTON_SPACESIM_RIGHT_LINK      = 117490924 (&H0700C4EC)
  DIBUTTON_SPACESIM_SLOWER_LINK     = 117687528 (&H0703C4E8)
  DIBUTTON_SPACESIM_TARGET          = 117441539 (&H07000403)
  DIBUTTON_SPACESIM_TURN_LEFT_LINK  = 117589220 (&H070244E4)
  DIBUTTON_SPACESIM_TURN_RIGHT_LINK = 117589228 (&H070244EC)
  DIBUTTON_SPACESIM_VIEW            = 117457924 (&H07004404)
  DIBUTTON_SPACESIM_WEAPONS         = 117441538 (&H07000402)
  DIBUTTON_STRATEGYR_APPLY          = 184550402 (&H0B000402)
  DIBUTTON_STRATEGYR_ATTACK         = 184550404 (&H0B000404)
  DIBUTTON_STRATEGYR_BACK_LINK      = 184632552 (&H0B0144E8)
  DIBUTTON_STRATEGYR_CAST           = 184550405 (&H0B000405)
  DIBUTTON_STRATEGYR_CROUCH         = 184550406 (&H0B000406)
  DIBUTTON_STRATEGYR_DEVICE         = 184567038 (&H0B0044FE)
  DIBUTTON_STRATEGYR_DISPLAY        = 184566793 (&H0B004409)
  DIBUTTON_STRATEGYR_FORWARD_LINK   = 184632544 (&H0B0144E0)
  DIBUTTON_STRATEGYR_GET            = 184550401 (&H0B000401)
  DIBUTTON_STRATEGYR_JUMP           = 184550407 (&H0B000407)
  DIBUTTON_STRATEGYR_LEFT_LINK      = 184599780 (&H0B00C4E4)
  DIBUTTON_STRATEGYR_MAP            = 184566792 (&H0B004408)
  DIBUTTON_STRATEGYR_MENU           = 184550653 (&H0B0004FD)
  DIBUTTON_STRATEGYR_PAUSE          = 184567036 (&H0B0044FC)
  DIBUTTON_STRATEGYR_RIGHT_LINK     = 184599788 (&H0B00C4EC)
  DIBUTTON_STRATEGYR_ROTATE_LEFT_LINK=184698084 (&H0B0244E4)
  DIBUTTON_STRATEGYR_ROTATE_RIGHT_LINK=184698092 (&HB0244EC)
  DIBUTTON_STRATEGYR_SELECT         = 184550403 (&H0B000403)
  DIBUTTON_STRATEGYT_APPLY          = 201327619 (&H0C000403)
  DIBUTTON_STRATEGYT_BACK_LINK      = 201409768 (&H0C0144E8)
  DIBUTTON_STRATEGYT_DEVICE         = 201344254 (&H0C0044FE)
  DIBUTTON_STRATEGYT_DISPLAY        = 201344008 (&H0C004408)
  DIBUTTON_STRATEGYT_FORWARD_LINK   = 201409760 (&H0C0144E0)
  DIBUTTON_STRATEGYT_INSTRUCT       = 201327618 (&H0C000402)
  DIBUTTON_STRATEGYT_LEFT_LINK      = 201376996 (&H0C00C4E4)
  DIBUTTON_STRATEGYT_MAP            = 201344007 (&H0C004407)
  DIBUTTON_STRATEGYT_MENU           = 201327869 (&H0C0004FD)
  DIBUTTON_STRATEGYT_PAUSE          = 201344252 (&H0C0044FC)
  DIBUTTON_STRATEGYT_RIGHT_LINK     = 201377004 (&H0C00C4EC)
  DIBUTTON_STRATEGYT_SELECT         = 201327617 (&H0C000401)
  DIBUTTON_STRATEGYT_TEAM           = 201327620 (&H0C000404)
  DIBUTTON_STRATEGYT_TURN           = 201327621 (&H0C000405)
  DIBUTTON_STRATEGYT_ZOOM           = 201344006 (&H0C004406)
  DIBUTTON_TPS_ACTION               = 167773186 (&H0A000402)
  DIBUTTON_TPS_BACKWARD_LINK        = 167855336 (&H0A0144E8)
  DIBUTTON_TPS_DEVICE               = 167789822 (&H0A0044FE)
  DIBUTTON_TPS_DODGE                = 167789577 (&H0A004409)
  DIBUTTON_TPS_FORWARD_LINK         = 167855328 (&H0A0144E0)
  DIBUTTON_TPS_GLANCE_DOWN_LINK     = 168281320 (&H0A07C4E8)
  DIBUTTON_TPS_GLANCE_LEFT_LINK     = 168281316 (&H0A07C4E4)
  DIBUTTON_TPS_GLANCE_RIGHT_LINK    = 168281324 (&H0A07C4EC)
  DIBUTTON_TPS_GLANCE_UP_LINK       = 168281312 (&H0A07C4E0)
  DIBUTTON_TPS_INVENTORY            = 167789578 (&H0A00440A)
  DIBUTTON_TPS_JUMP                 = 167773189 (&H0A000405)
  DIBUTTON_TPS_MENU                 = 167773437 (&H0A0004FD)
  DIBUTTON_TPS_PAUSE                = 167789820 (&H0A0044FC)
  DIBUTTON_TPS_RUN                  = 167773185 (&H0A000401)
  DIBUTTON_TPS_SELECT               = 167773187 (&H0A000403)
  DIBUTTON_TPS_STEPLEFT             = 167789575 (&H0A004407)
  DIBUTTON_TPS_STEPRIGHT            = 167789576 (&H0A004408)
  DIBUTTON_TPS_TURN_LEFT_LINK       = 167920868 (&H0A0244E4)
  DIBUTTON_TPS_TURN_RIGHT_LINK      = 167920876 (&H0A0244EC)
  DIBUTTON_TPS_USE                  = 167773188 (&H0A000404)
  DIBUTTON_TPS_VIEW                 = 167789574 (&H0A004406)
  DIHATSWITCH_2DCONTROL_HATSWITCH   = 587220481 (&H23004601)
  DIHATSWITCH_3DCONTROL_HATSWITCH   = 603997697 (&H24004601)
  DIHATSWITCH_ARCADEP_VIEW          = 570443265 (&H22004601)
  DIHATSWITCH_ARCADES_VIEW          = 553666049 (&H21004601)
  DIHATSWITCH_BBALLD_GLANCE         = 318785025 (&H13004601)
  DIHATSWITCH_BBALLO_GLANCE         = 302007809 (&H12004601)
  DIHATSWITCH_BIKINGM_SCROLL        = 469779969 (&H1C004601)
  DIHATSWITCH_CADF_HATSWITCH        = 620774913 (&H25004601)
  DIHATSWITCH_CADM_HATSWITCH        = 637552129 (&H26004601)
  DIHATSWITCH_DRIVINGC_GLANCE       =  33572353 (&H02004601)
  DIHATSWITCH_DRIVINGR_GLANCE       =  16795137 (&H01004601)
  DIHATSWITCH_DRIVINGT_GLANCE       =  50349569 (&H03004601)
  DIHATSWITCH_FIGHTINGH_SLIDE       = 134235649 (&H08004601)
  DIHATSWITCH_FISHING_GLANCE        = 234898945 (&H0E004601)
  DIHATSWITCH_FLYINGC_GLANCE        =  67126785 (&H04004601)
  DIHATSWITCH_FLYINGH_GLANCE        = 100681217 (&H06004601)
  DIHATSWITCH_FLYINGM_GLANCE        =  83904001 (&H05004601)
  DIHATSWITCH_FPS_GLANCE            = 151012865 (&H09004601)
  DIHATSWITCH_GOLF_SCROLL           = 402671105 (&H18004601)
  DIHATSWITCH_HOCKEYD_SCROLL        = 436225537 (&H1A004601)
  DIHATSWITCH_HOCKEYG_SCROLL        = 453002753 (&H1B004601)
  DIHATSWITCH_HOCKEYO_SCROLL        = 419448321 (&H19004601)
  DIHATSWITCH_HUNTING_GLANCE        = 218121729 (&H0D004601)
  DIHATSWITCH_MECHA_GLANCE          = 687883777 (&H29004601)
  DIHATSWITCH_RACQUET_GLANCE        = 536888833 (&H20004601)
  DIHATSWITCH_SKIING_GLANCE         = 486557185 (&H1D004601)
  DIHATSWITCH_SOCCERD_GLANCE        = 520111617 (&H1F004601)
  DIHATSWITCH_SOCCERO_GLANCE        = 503334401 (&H1E004601)
  DIHATSWITCH_SPACESIM_GLANCE       = 117458433 (&H07004601)
  DIHATSWITCH_STRATEGYR_GLANCE      = 184567297 (&H0B004601)
  DIHATSWITCH_TPS_GLANCE            = 167790081 (&H0A004601)
  DIVIRTUAL_ARCADE_PLATFORM         = 570425344 (&H22000000)
  DIVIRTUAL_ARCADE_SIDE2SIDE        = 553648128 (&H21000000)
  DIVIRTUAL_BROWSER_CONTROL         = 671088640 (&H28000000)
  DIVIRTUAL_CAD_2DCONTROL           = 587202560 (&H23000000)
  DIVIRTUAL_CAD_3DCONTROL           = 603979776 (&H24000000)
  DIVIRTUAL_CAD_FLYBY               = 620756992 (&H25000000)
  DIVIRTUAL_CAD_MODEL               = 637534208 (&H26000000)
  DIVIRTUAL_DRIVING_COMBAT          =  33554432 (&H02000000)
  DIVIRTUAL_DRIVING_MECHA           = 687865856 (&H29000000)
  DIVIRTUAL_DRIVING_RACE            =  16777216 (&H01000000)
  DIVIRTUAL_DRIVING_TANK            =  50331648 (&H03000000)
  DIVIRTUAL_FIGHTING_FPS            = 150994944 (&H09000000)
  DIVIRTUAL_FIGHTING_HAND2HAND      = 134217728 (&H08000000)
  DIVIRTUAL_FIGHTING_THIRDPERSON    = 167772160 (&H0A000000)
  DIVIRTUAL_FLYING_CIVILIAN         =  67108864 (&H04000000)
  DIVIRTUAL_FLYING_HELICOPTER       = 100663296 (&H06000000)
  DIVIRTUAL_FLYING_MILITARY         =  83886080 (&H05000000)
  DIVIRTUAL_REMOTE_CONTROL          = 654311424 (&H27000000)
  DIVIRTUAL_SPACESIM                = 117440512 (&H07000000)
  DIVIRTUAL_SPORTS_BASEBALL_BAT     = 251658240 (&H0F000000)
  DIVIRTUAL_SPORTS_BASEBALL_FIELD   = 285212672 (&H11000000)
  DIVIRTUAL_SPORTS_BASEBALL_PITCH   = 268435456 (&H10000000)
  DIVIRTUAL_SPORTS_BASKETBALL_DEFENSE=318767104 (&H13000000)
  DIVIRTUAL_SPORTS_BASKETBALL_OFFENSE=301989888 (&H12000000)
  DIVIRTUAL_SPORTS_BIKING_MOUNTAIN  = 469762048 (&H1C000000)
  DIVIRTUAL_SPORTS_FISHING          = 234881024 (&H0E000000)
  DIVIRTUAL_SPORTS_FOOTBALL_DEFENSE = 385875968 (&H17000000)
  DIVIRTUAL_SPORTS_FOOTBALL_FIELD   = 335544320 (&H14000000)
  DIVIRTUAL_SPORTS_FOOTBALL_OFFENSE = 369098752 (&H16000000)
  DIVIRTUAL_SPORTS_FOOTBALL_QBCK    = 352321536 (&H15000000)
  DIVIRTUAL_SPORTS_GOLF             = 402653184 (&H18000000)
  DIVIRTUAL_SPORTS_HOCKEY_DEFENSE   = 436207616 (&H1A000000)
  DIVIRTUAL_SPORTS_HOCKEY_GOALIE    = 452984832 (&H1B000000)
  DIVIRTUAL_SPORTS_HOCKEY_OFFENSE   = 419430400 (&H19000000)
  DIVIRTUAL_SPORTS_HUNTING          = 218103808 (&H0D000000)
  DIVIRTUAL_SPORTS_RACQUET          = 536870912 (&H20000000)
  DIVIRTUAL_SPORTS_SKIING           = 486539264 (&H1D000000)
  DIVIRTUAL_SPORTS_SOCCER_DEFENSE   = 520093696 (&H1F000000)
  DIVIRTUAL_SPORTS_SOCCER_OFFENSE   = 503316480 (&H1E000000)
  DIVIRTUAL_STRATEGY_ROLEPLAYING    = 184549376 (&H0B000000)
  DIVIRTUAL_STRATEGY_TURN           = 201326592 (&H0C000000)
End Enum


CONST_DIGFFSFLAGS

この列挙のメンバは、フォース フィードバック デバイスの状態を表す。DirectInputDevice8.GetForceFeedbackState メソッドにより取得される。

Enum CONST_DIGFFSFLAGS
    DIGFFS_ACTUATORSOFF    =          32 (&H20)
    DIGFFS_ACTUATORSON     =          16 (&H10)
    DIGFFS_DEVICELOST      = -2147483648 (&H80000000)
    DIGFFS_EMPTY           =           1
    DIGFFS_PAUSED          =           4
    DIGFFS_POWEROFF        =         128 (&H80)
    DIGFFS_POWERON         =          64 (&H40)
    DIGFFS_SAFETYSWITCHOFF =         512 (&H200)
    DIGFFS_SAFETYSWITCHON  =         256 (&H100)
    DIGFFS_STOPPED         =           2
    DIGFFS_USERFFSWITCHOFF =        2048 (&H800)
    DIGFFS_USERFFSWITCHON  =        1024 (&H400)
End Enum

定数

DIGFFS_ACTUATORSOFF
デバイスのフォース フィードバック アクチュエータが無効である。
DIGFFS_ACTUATORSON
デバイスのフォース フィードバック アクチュエータが有効である。
DIGFFS_DEVICELOST
デバイスが予期しない障害を被り、不確定な状態にある。一度デバイスを解放した後で再取得するか、または DISFFC_RESET コマンドを送信するかどちらかでデバイスをリセットしなければならない。
DIGFFS_EMPTY
デバイスはダウンロードされた要素を持たない。
DIGFFS_PAUSED
すべてのアクティブなエフェクトの再生が一時停止されている。
DIGFFS_POWEROFF
フォース フィードバック システムは、現在使用できない。デバイスが電源状態を報告できなければ、DIFFS_POWERON および DIFFS_POWEROFF のどちらも返されない。
DIGFFS_POWERON
フォース フィードバック システムの電源は現在入っている。デバイスが電源状態を報告できなければ、DIFFS_POWERON および DIFFS_POWEROFF のどちらも返されない。
DIGFFS_SAFETYSWITCHOFF
安全スイッチが現在オフである。つまり、デバイスは動作できない。デバイスが安全スイッチの状態を報告できなければ、DIFFS_SAFETYSWITCHON および DIFFS_SAFETYSWITCHOFF のどちらも返されない。
DIGFFS_SAFETYSWITCHON
安全スイッチが現在オンである。つまり、デバイスは動作できる。デバイスが安全スイッチの状態を報告できなければ、DIFFS_SAFETYSWITCHON および DIFFS_SAFETYSWITCHOFF のどちらも返されない。
DIGFFS_STOPPED
再生中のエフェクトはなく、デバイスは中断状態ではない。
DIGFFS_USERFFSWITCHOFF
ユーザー フォース フィードバック スイッチが現在オフである。つまり、デバイスは動作できない。デバイスがユーザー フォース フィードバック スイッチの状態を報告できなければ、DIFFS_USERFFSWITCHON および DIFFS_USERFFSWITCHOFF のどちらも返されない。
DIGFFS_USERFFSWITCHON
ユーザー フォース フィードバック スイッチが現在オンである。つまり、デバイスは動作できる。デバイスがユーザー フォース フィードバック スイッチの状態を報告できなければ、DIFFS_USERFFSWITCHON および DIFFS_USERFFSWITCHOFF のどちらも返されない。


CONST_DIJOYSTICKOFS

ジョイスティック データ内のデバイス オブジェクトを識別するために使用される。定数の値は、直接データのデータ形式内のデータのオフセットである。同じ識別子がバッファリング データ パケットで使用される。

Enum CONST_DIJOYSTICKOFS
    DIJOFS_BUTTON0  = 48 (&H30)
    DIJOFS_BUTTON1  = 49 (&H31)
    DIJOFS_BUTTON2  = 50 (&H32)
    DIJOFS_BUTTON3  = 51 (&H33)
    DIJOFS_BUTTON4  = 52 (&H34)
    DIJOFS_BUTTON5  = 53 (&H35)
    DIJOFS_BUTTON6  = 54 (&H36)
    DIJOFS_BUTTON7  = 55 (&H37)
    DIJOFS_BUTTON8  = 56 (&H38)
    DIJOFS_BUTTON9  = 57 (&H39)
    DIJOFS_BUTTON10 = 58 (&H3A)
    DIJOFS_BUTTON11 = 59 (&H3B)
    DIJOFS_BUTTON12 = 60 (&H3C)
    DIJOFS_BUTTON13 = 61 (&H3D)
    DIJOFS_BUTTON14 = 62 (&H3E)
    DIJOFS_BUTTON15 = 63 (&H3F)
    DIJOFS_BUTTON16 = 64 (&H40)
    DIJOFS_BUTTON17 = 65 (&H41)
    DIJOFS_BUTTON18 = 66 (&H42)
    DIJOFS_BUTTON19 = 67 (&H43)
    DIJOFS_BUTTON20 = 68 (&H44)
    DIJOFS_BUTTON21 = 69 (&H45)
    DIJOFS_BUTTON22 = 70 (&H46)
    DIJOFS_BUTTON23 = 71 (&H47)
    DIJOFS_BUTTON24 = 72 (&H48)
    DIJOFS_BUTTON25 = 73 (&H49)
    DIJOFS_BUTTON26 = 74 (&H4A)
    DIJOFS_BUTTON27 = 75 (&H4B)
    DIJOFS_BUTTON28 = 76 (&H4C)
    DIJOFS_BUTTON29 = 77 (&H4D)
    DIJOFS_BUTTON30 = 78 (&H4E)
    DIJOFS_BUTTON31 = 79 (&H4F)
    DIJOFS_POV0     = 32 (&H20)
    DIJOFS_POV1     = 36 (&H24)
    DIJOFS_POV2     = 40 (&H28)
    DIJOFS_POV3     = 44 (&H2C)
    DIJOFS_RX       = 12
    DIJOFS_RY       = 16 (&H10)
    DIJOFS_RZ       = 20 (&H14)
    DIJOFS_SLIDER0  = 24 (&H18)
    DIJOFS_SLIDER1  = 28 (&H1C)
    DIJOFS_X        =  0
    DIJOFS_Y        =  4
    DIJOFS_Z        =  8
End Enum

定数

DIJOFS_BUTTON(n)
ボタン n のデータのオフセット。
DIJOFS_POV0, DIJOFS_POV1, DIJOFS_POV2, DIJOFS_POV3
視点コントローラのデータのオフセット。
DIJOFS_RX, DIJOFS_RY, DIJOFS_RZ
軸回転のデータのオフセット。
DIJOFS_SLIDER0, DIJOFS_SLIDER1
スライダのデータのオフセット。
DIJOFS_X, DIJOFS_Y, DIJOFS_Z
軸のデータのオフセット。


CONST_DIKEYBOARDFLAGS

DIACTION 型の lSemantic メンバに特定のキーを指定するために使用される。

Enum CONST_DIKEYBOARDFLAGS
    DIKEYBOARD_0            = -2130705397 (&H8100040B)
    DIKEYBOARD_1            = -2130705406 (&H81000402)
    DIKEYBOARD_2            = -2130705405 (&H81000403)
    DIKEYBOARD_3            = -2130705404 (&H81000404)
    DIKEYBOARD_4            = -2130705403 (&H81000405)
    DIKEYBOARD_5            = -2130705402 (&H81000406)
    DIKEYBOARD_6            = -2130705401 (&H81000407)
    DIKEYBOARD_7            = -2130705400 (&H81000408)
    DIKEYBOARD_8            = -2130705399 (&H81000409)
    DIKEYBOARD_9            = -2130705398 (&H8100040A)
    DIKEYBOARD_A            = -2130705378 (&H8100041E)
    DIKEYBOARD_ABNT_C1      = -2130705293 (&H81000473)
    DIKEYBOARD_ABNT_C2      = -2130705282 (&H8100047E)
    DIKEYBOARD_ADD          = -2130705330 (&H8100044E)
    DIKEYBOARD_APOSTROPHE   = -2130705368 (&H81000428)
    DIKEYBOARD_APPS         = -2130705187 (&H810004DD)
    DIKEYBOARD_AT           = -2130705263 (&H81000491)
    DIKEYBOARD_AX           = -2130705258 (&H81000496)
    DIKEYBOARD_B            = -2130705360 (&H81000430)
    DIKEYBOARD_BACK         = -2130705394 (&H8100040E)
    DIKEYBOARD_BACKSLASH    = -2130705365 (&H8100042B)
    DIKEYBOARD_C            = -2130705362 (&H8100042E)
    DIKEYBOARD_CALCULATOR   = -2130705247 (&H810004A1)
    DIKEYBOARD_CAPITAL      = -2130705350 (&H8100043A)
    DIKEYBOARD_COLON        = -2130705262 (&H81000492)
    DIKEYBOARD_COMMA        = -2130705357 (&H81000433)
    DIKEYBOARD_CONVERT      = -2130705287 (&H81000479)
    DIKEYBOARD_D            = -2130705376 (&H81000420)
    DIKEYBOARD_DECIMAL      = -2130705325 (&H81000453)
    DIKEYBOARD_DELETE       = -2130705197 (&H810004D3)
    DIKEYBOARD_DIVIDE       = -2130705227 (&H810004B5)
    DIKEYBOARD_DOWN         = -2130705200 (&H810004D0)
    DIKEYBOARD_E            = -2130705390 (&H81000412)
    DIKEYBOARD_END          = -2130705201 (&H810004CF)
    DIKEYBOARD_EQUALS       = -2130705395 (&H8100040D)
    DIKEYBOARD_ESCAPE       = -2130705407 (&H81000401)
    DIKEYBOARD_F            = -2130705375 (&H81000421)
    DIKEYBOARD_F1           = -2130705349 (&H8100043B)
    DIKEYBOARD_F2           = -2130705348 (&H8100043C)
    DIKEYBOARD_F3           = -2130705347 (&H8100043D)
    DIKEYBOARD_F4           = -2130705346 (&H8100043E)
    DIKEYBOARD_F5           = -2130705345 (&H8100043F)
    DIKEYBOARD_F6           = -2130705344 (&H81000440)
    DIKEYBOARD_F7           = -2130705343 (&H81000441)
    DIKEYBOARD_F8           = -2130705342 (&H81000442)
    DIKEYBOARD_F9           = -2130705341 (&H81000443)
    DIKEYBOARD_F10          = -2130705340 (&H81000444)
    DIKEYBOARD_F11          = -2130705321 (&H81000457)
    DIKEYBOARD_F12          = -2130705320 (&H81000458)
    DIKEYBOARD_F13          = -2130705308 (&H81000464)
    DIKEYBOARD_F14          = -2130705307 (&H81000465)
    DIKEYBOARD_F15          = -2130705306 (&H81000466)
    DIKEYBOARD_G            = -2130705374 (&H81000422)
    DIKEYBOARD_GRAVE        = -2130705367 (&H81000429)
    DIKEYBOARD_H            = -2130705373 (&H81000423)
    DIKEYBOARD_HOME         = -2130705209 (&H810004C7)
    DIKEYBOARD_I            = -2130705385 (&H81000417)
    DIKEYBOARD_INSERT       = -2130705198 (&H810004D2)
    DIKEYBOARD_J            = -2130705372 (&H81000424)
    DIKEYBOARD_K            = -2130705371 (&H81000425)
    DIKEYBOARD_KANA         = -2130705296 (&H81000470)
    DIKEYBOARD_KANJI        = -2130705260 (&H81000494)
    DIKEYBOARD_L            = -2130705370 (&H81000426)
    DIKEYBOARD_LBRACKET     = -2130705382 (&H8100041A)
    DIKEYBOARD_LCONTROL     = -2130705379 (&H8100041D)
    DIKEYBOARD_LEFT         = -2130705205 (&H810004CB)
    DIKEYBOARD_LMENU        = -2130705352 (&H81000438)
    DIKEYBOARD_LSHIFT       = -2130705366 (&H8100042A)
    DIKEYBOARD_LWIN         = -2130705189 (&H810004DB)
    DIKEYBOARD_M            = -2130705358 (&H81000432)
    DIKEYBOARD_MAIL         = -2130705172 (&H810004EC)
    DIKEYBOARD_MEDIASELECT  = -2130705171 (&H810004ED)
    DIKEYBOARD_MEDIASTOP    = -2130705244 (&H810004A4)
    DIKEYBOARD_MINUS        = -2130705396 (&H8100040C)
    DIKEYBOARD_MULTIPLY     = -2130705353 (&H81000437)
    DIKEYBOARD_MUTE         = -2130705248 (&H810004A0)
    DIKEYBOARD_MYCOMPUTER   = -2130705173 (&H810004EB)
    DIKEYBOARD_N            = -2130705359 (&H81000431)
    DIKEYBOARD_NEXT         = -2130705199 (&H810004D1)
    DIKEYBOARD_NEXTTRACK    = -2130705255 (&H81000499)
    DIKEYBOARD_NOCONVERT    = -2130705285 (&H8100047B)
    DIKEYBOARD_NUMLOCK      = -2130705339 (&H81000445)
    DIKEYBOARD_NUMPAD0      = -2130705326 (&H81000452)
    DIKEYBOARD_NUMPAD1      = -2130705329 (&H8100044F)
    DIKEYBOARD_NUMPAD2      = -2130705328 (&H81000450)
    DIKEYBOARD_NUMPAD3      = -2130705327 (&H81000451)
    DIKEYBOARD_NUMPAD4      = -2130705333 (&H8100044B)
    DIKEYBOARD_NUMPAD5      = -2130705332 (&H8100044C)
    DIKEYBOARD_NUMPAD6      = -2130705331 (&H8100044D)
    DIKEYBOARD_NUMPAD7      = -2130705337 (&H81000447)
    DIKEYBOARD_NUMPAD8      = -2130705336 (&H81000448)
    DIKEYBOARD_NUMPAD9      = -2130705335 (&H81000449)
    DIKEYBOARD_NUMPADCOMMA  = -2130705229 (&H810004B3)
    DIKEYBOARD_NUMPADENTER  = -2130705252 (&H8100049C)
    DIKEYBOARD_NUMPADEQUALS = -2130705267 (&H8100048D)
    DIKEYBOARD_O            = -2130705384 (&H81000418)
    DIKEYBOARD_OEM_102      = -2130705322 (&H81000456)
    DIKEYBOARD_P            = -2130705383 (&H81000419)
    DIKEYBOARD_PAUSE        = -2130705211 (&H810004C5)
    DIKEYBOARD_PERIOD       = -2130705356 (&H81000434)
    DIKEYBOARD_PLAYPAUSE    = -2130705246 (&H810004A2)
    DIKEYBOARD_POWER        = -2130705186 (&H810004DE)
    DIKEYBOARD_PREVTRACK    = -2130705264 (&H81000490)
    DIKEYBOARD_PRIOR        = -2130705207 (&H810004C9)
    DIKEYBOARD_Q            = -2130705392 (&H81000410)
    DIKEYBOARD_R            = -2130705389 (&H81000413)
    DIKEYBOARD_RBRACKET     = -2130705381 (&H8100041B)
    DIKEYBOARD_RCONTROL     = -2130705251 (&H8100049D)
    DIKEYBOARD_RETURN       = -2130705380 (&H8100041C)
    DIKEYBOARD_RIGHT        = -2130705203 (&H810004CD)
    DIKEYBOARD_RMENU        = -2130705224 (&H810004B8)
    DIKEYBOARD_RSHIFT       = -2130705354 (&H81000436)
    DIKEYBOARD_RWIN         = -2130705188 (&H810004DC)
    DIKEYBOARD_S            = -2130705377 (&H8100041F)
    DIKEYBOARD_SCROLL       = -2130705338 (&H81000446)
    DIKEYBOARD_SEMICOLON    = -2130705369 (&H81000427)
    DIKEYBOARD_SLASH        = -2130705355 (&H81000435)
    DIKEYBOARD_SLEEP        = -2130705185 (&H810004DF)
    DIKEYBOARD_SPACE        = -2130705351 (&H81000439)
    DIKEYBOARD_STOP         = -2130705259 (&H81000495)
    DIKEYBOARD_SUBTRACT     = -2130705334 (&H8100044A)
    DIKEYBOARD_SYSRQ        = -2130705225 (&H810004B7)
    DIKEYBOARD_T            = -2130705388 (&H81000414)
    DIKEYBOARD_TAB          = -2130705393 (&H8100040F)
    DIKEYBOARD_U            = -2130705386 (&H81000416)
    DIKEYBOARD_UNDERLINE    = -2130705261 (&H81000493)
    DIKEYBOARD_UNLABELED    = -2130705257 (&H81000497)
    DIKEYBOARD_UP           = -2130705208 (&H810004C8)
    DIKEYBOARD_V            = -2130705361 (&H8100042F)
    DIKEYBOARD_VOLUMEDOWN   = -2130705234 (&H810004AE)
    DIKEYBOARD_VOLUMEUP     = -2130705232 (&H810004B0)
    DIKEYBOARD_W            = -2130705391 (&H81000411)
    DIKEYBOARD_WAKE         = -2130705181 (&H810004E3)
    DIKEYBOARD_WEBBACK      = -2130705174 (&H810004EA)
    DIKEYBOARD_WEBFAVORITES = -2130705178 (&H810004E6)
    DIKEYBOARD_WEBFORWARD   = -2130705175 (&H810004E9)
    DIKEYBOARD_WEBHOME      = -2130705230 (&H810004B2)
    DIKEYBOARD_WEBREFRESH   = -2130705177 (&H810004E7)
    DIKEYBOARD_WEBSEARCH    = -2130705179 (&H810004E5)
    DIKEYBOARD_WEBSTOP      = -2130705176 (&H810004E8)
    DIKEYBOARD_X            = -2130705363 (&H8100042D)
    DIKEYBOARD_Y            = -2130705387 (&H81000415)
    DIKEYBOARD_YEN          = -2130705283 (&H8100047D)
    DIKEYBOARD_Z            = -2130705364 (&H8100042C)
End Enum

定数

DIKEYBOARD_(n)
メイン キーボード上の数字キー 0 ～ 9
DIKEYBOARD_A�DIKEYBOARD_Z
メイン キーボード上の文字キー A ～ Z
DIKEYBOARD_ABNT_C1, DIKEYBOARD_ABNT_C2
ブラジル語キーボードのテンキー上
DIKEYBOARD_ADD
テンキー上のプラス記号 (+)
DIKEYBOARD_APOSTROPHE
アポストロフィ (') キー
DIKEYBOARD_APPS
アプリケーション キー
DIKEYBOARD_AT
日本語キーボード上
DIKEYBOARD_AX
日本語キーボード上
DIKEYBOARD_BACK
Backspace キー
DIKEYBOARD_BACKSLASH
円記号 (\) キー
DIKEYBOARD_CALCULATOR
電卓起動専用キー
DIKEYBOARD_CAPITAL
CapsLock キー
DIKEYBOARD_COLON
日本語キーボード上
DIKEYBOARD_COMMA
カンマ (,) キー
DIKEYBOARD_CONVERT
日本語キーボード上
DIKEYBOARD_DECIMAL
テンキー上のピリオド (小数点)
DIKEYBOARD_DELETE
メイン キーボード上の Delete キー (テンキー上の Del ではない)
DIKEYBOARD_DIVIDE
テンキー上のスラッシュ (/)
DIKEYBOARD_DOWN, DIKEYBOARD_UP
メイン キーボード上の下矢印キー、上矢印キー (テンキー上の矢印キーではない)
DIKEYBOARD_END
メイン キーボード上の End キー (テンキー上の End ではない)
DIKEYBOARD_EQUALS
メイン キーボード上の等号
DIKEYBOARD_ESCAPE
Esc キー
DIKEYBOARD_F(n)
ファンクション キー F1 ～ F15
DIKEYBOARD_GRAVE
アクサン グラーブ (`) キー
DIKEYBOARD_HOME
メイン キーボード上の Home キー (テンキー上の Home ではない)
DIKEYBOARD_INSERT
メイン キーボード上の Insert キー (テンキー上の Ins ではない)
DIKEYBOARD_KANA
日本語キーボード上
DIKEYBOARD_KANJI
日本語キーボード上
DIKEYBOARD_LBRACKET, DIKEYBOARD_RBRACKET
左 ([) および右 (]) の角かっこキー
DIKEYBOARD_LCONTROL, DIKEYBOARD_RCONTROL
左右の Ctrl キー
DIKEYBOARD_LEFT, DIKEYBOARD_RIGHT
メイン キーボード上の左矢印キー、右矢印キー (テンキー上の矢印キーではない)
DIKEYBOARD_LMENU, DIKEYBOARD_RMENU
左右の Alt キー
DIKEYBOARD_LSHIFT, DIKEYBOARD_RSHIFT
左右の Shift キー
DIKEYBOARD_LWIN, DIKEYBOARD_RWIN
左右の Microsoft® Windows® キー
DIKEYBOARD_MAIL
電子メール プログラム起動専用キー
DIKEYBOARD_MEDIASELECT
システムでサポートされているメディア プレーヤーの選択を表示する、メディア選択キー。
DIKEYBOARD_MEDIASTOP
マルチメディアの再生を停止する
DIKEYBOARD_MINUS
メイン キーボード上のハイフン (-) (マイナス記号)
DIKEYBOARD_MULTIPLY
テンキー上のアスタリスク キー (*)
DIKEYBOARD_MUTE
サウンド出力をミュートする
DIKEYBOARD_MYCOMPUTER
対応している Windows システムでマイ コンピュータを起動する
DIKEYBOARD_NEXT
メイン キーボード上の PageDown キー (テンキー上の PgDn ではない)
DIKEYBOARD_NEXTTRACK
CD または DVD の次のトラックに進む
DIKEYBOARD_NOCONVERT
日本語キーボード上
DIKEYBOARD_NUMLOCK
NumLock キー
DIKEYBOARD_NUMPAD(n)
テンキー上の数字キー
DIKEYBOARD_NUMPADCOMMA
NEC PC98 テンキー上のカンマ (,)
DIKEYBOARD_NUMPADENTER
テンキー上の Enter キー
DIKEYBOARD_NUMPADEQUALS
NEC PC98 キーボードのテンキー上の等号
DIKEYBOARD_OEM_102
英語キーボードおよびドイツ語キーボード上
DIKEYBOARD_PAUSE
Pause キー
DIKEYBOARD_PERIOD
メイン キーボード上の Enter キー
DIKEYBOARD_PLAYPAUSE
マルチメディアの再生を一時停止する
DIKEYBOARD_POWER
システム電源キー
DIKEYBOARD_PREVTRACK
CD または DVD の前のトラックを再生する、日本語キーボードのサーカムフレックス
DIKEYBOARD_PRIOR
メイン キーボード上の PageUp キー (テンキー上の PgUp ではない)
DIKEYBOARD_RETURN
メイン キーボード上の Enter キー
DIKEYBOARD_SCROLL
ScrollLock キー
DIKEYBOARD_SEMICOLON
セミコロン (;) キー
DIKEYBOARD_SLASH
メイン キーボード上のスラッシュ (/) (テンキー上のスラッシュではない)
DIKEYBOARD_SLEEP
システムをスリープ モードに移行する
DIKEYBOARD_SPACE
Space キー
DIKEYBOARD_STOP
日本語キーボード上
DIKEYBOARD_SUBTRACT
テンキー上のマイナス記号
DIKEYBOARD_SYSRQ
SysRq キー
DIKEYBOARD_TAB
Tab キー
DIKEYBOARD_UNDERLINE
日本語キーボード上
DIKEYBOARD_UNLABELED
日本語キーボード上
DIKEYBOARD_VOLUMEDOWN
サウンド出力レベルを下げる
DIKEYBOARD_VOLUMEUP
サウンド出力レベルを上げる
DIKEYBOARD_WAKE
システムをスリープ モードから復帰させる
DIKEYBOARD_WEBBACK
ブラウザを履歴一覧の 1 ページ前に戻す
DIKEYBOARD_WEBFAVORITES
Microsoft Internet Explorer の [お気に入り] リスト、Windows の [Favorites] フォルダ、または Netscape のブックマーク リストを表示する。
DIKEYBOARD_WEBFORWARD
ブラウザに対して履歴一覧の次のページへの移動を指示する
DIKEYBOARD_WEBHOME
ブラウザに対してユーザーのホーム ページの読み込みを指示する
DIKEYBOARD_WEBREFRESH
ブラウザに対して現在のページの再読み込みを指示する
DIKEYBOARD_WEBSEARCH
ブラウザに対して検索エンジンの起動を指示する
DIKEYBOARD_WEBSTOP
ブラウザに対して現在のページの読み込み停止を指示する
DIKEYBOARD_YEN
日本語キーボード上

この列挙の定数は、CONST_DIKEYFLAGS のメンバに対応するが、この場合、名前の先頭に付くのは DIKEYBOARD ではなく DIK であり、異なる値を持つ。


CONST_DIKEYFLAGS

キーボード データ内のキーを識別するために使用される。

Enum CONST_DIKEYFLAGS
    DIK_0            =  11
    DIK_1            =   2
    DIK_2            =   3
    DIK_3            =   4
    DIK_4            =   5
    DIK_5            =   6
    DIK_6            =   7
    DIK_7            =   8
    DIK_8            =   9
    DIK_9            =  10
    DIK_A            =  30 (&H1E)
    DIK_ABNT_C1      = 115 (&H73)
    DIK_ABNT_C2      = 126 (&H7E)
    DIK_ADD          =  78 (&H4E)
    DIK_APOSTROPHE   =  40 (&H28)
    DIK_APPS         = 221 (&HDD)
    DIK_AT           = 145 (&H91)
    DIK_AX           = 150 (&H96)
    DIK_B            =  48 (&H30)
    DIK_BACK         =  14
    DIK_BACKSLASH    =  43 (&H2B)
    DIK_BACKSPACE    =  14
    DIK_C            =  46 (&H2E)
    DIK_CALCULATOR   = 161 (&HA1)
    DIK_CAPITAL      =  58 (&H3A)
    DIK_CAPSLOCK     =  58 (&H3A)
    DIK_CIRCUMFLEX   = 144 (&H90)
    DIK_COLON        = 146 (&H92)
    DIK_COMMA        =  51 (&H33)
    DIK_CONVERT      = 121 (&H79)
    DIK_D            =  32 (&H20)
    DIK_DECIMAL      =  83 (&H53)
    DIK_DELETE       = 211 (&HD3)
    DIK_DIVIDE       = 181 (&HB5)
    DIK_DOWN         = 208 (&HD0)
    DIK_DOWNARROW    = 208 (&HD0)
    DIK_E            =  18 (&H12)
    DIK_END          = 207 (&HCF)
    DIK_EQUALS       =  13
    DIK_ESCAPE       =   1
    DIK_F            =  33 (&H21)
    DIK_F1           =  59 (&H3B)
    DIK_F2           =  60 (&H3C)
    DIK_F3           =  61 (&H3D)
    DIK_F4           =  62 (&H3E)
    DIK_F5           =  63 (&H3F)
    DIK_F6           =  64 (&H40)
    DIK_F7           =  65 (&H41)
    DIK_F8           =  66 (&H42)
    DIK_F9           =  67 (&H43)
    DIK_F10          =  68 (&H44)
    DIK_F11          =  87 (&H57)
    DIK_F12          =  88 (&H58)
    DIK_F13          = 100 (&H64)
    DIK_F14          = 101 (&H65)
    DIK_F15          = 102 (&H66)
    DIK_G            =  34 (&H22)
    DIK_GRAVE        =  41 (&H29)
    DIK_H            =  35 (&H23)
    DIK_HOME         = 199 (&HC7)
    DIK_I            =  23 (&H17)
    DIK_INSERT       = 210 (&HD2)
    DIK_J            =  36 (&H24)
    DIK_K            =  37 (&H25)
    DIK_KANA         = 112 (&H70)
    DIK_KANJI        = 148 (&H94)
    DIK_L            =  38 (&H26)
    DIK_LALT         =  56 (&H38)
    DIK_LBRACKET     =  26 (&H1A)
    DIK_LCONTROL     =  29 (&H1D)
    DIK_LEFT         = 203 (&HCB)
    DIK_LEFTARROW    = 203 (&HCB)
    DIK_LMENU        =  56 (&H38)
    DIK_LSHIFT       =  42 (&H2A)
    DIK_LWIN         = 219 (&HDB)
    DIK_M            =  50 (&H32)
    DIK_MAIL         = 236 (&HEC)
    DIK_MEDIASELECT  = 237 (&HED)
    DIK_MEDIASTOP    = 164 (&HA4)
    DIK_MINUS        =  12
    DIK_MULTIPLY     =  55 (&H37)
    DIK_MUTE         = 160 (&HA0)
    DIK_MYCOMPUTER   = 235 (&HEB)
    DIK_N            =  49 (&H31)
    DIK_NEXT         = 209 (&HD1)
    DIK_NEXTTRACK    = 153 (&H99)
    DIK_NOCONVERT    = 123 (&H7B)
    DIK_NUMLOCK      =  69 (&H45)
    DIK_NUMPAD0      =  82 (&H52)
    DIK_NUMPAD1      =  79 (&H4F)
    DIK_NUMPAD2      =  80 (&H50)
    DIK_NUMPAD3      =  81 (&H51)
    DIK_NUMPAD4      =  75 (&H4B)
    DIK_NUMPAD5      =  76 (&H4C)
    DIK_NUMPAD6      =  77 (&H4D)
    DIK_NUMPAD7      =  71 (&H47)
    DIK_NUMPAD8      =  72 (&H48)
    DIK_NUMPAD9      =  73 (&H49)
    DIK_NUMPADCOMMA  = 179 (&HB3)
    DIK_NUMPADENTER  = 156 (&H9C)
    DIK_NUMPADEQUALS = 141 (&H8D)
    DIK_NUMPADMINUS  =  74 (&H4A)
    DIK_NUMPADPERIOD =  83 (&H53)
    DIK_NUMPADPLUS   =  78 (&H4E)
    DIK_NUMPADSLASH  = 181 (&HB5)
    DIK_NUMPADSTAR   =  55 (&H37)
    DIK_O            =  24 (&H18)
    DIK_OEM_102      =  86 (&H56)
    DIK_P            =  25 (&H19)
    DIK_PAUSE        = 197 (&HC5)
    DIK_PERIOD       =  52 (&H34)
    DIK_PGDN         = 209 (&HD1)
    DIK_PGUP         = 201 (&HC9)
    DIK_PLAYPAUSE    = 162 (&HA2)
    DIK_POWER        = 222 (&HDE)
    DIK_PREVTRACK    = 144 (&H90)
    DIK_PRIOR        = 201 (&HC9)
    DIK_Q            =  16 (&H10)
    DIK_R            =  19 (&H13)
    DIK_RALT         = 184 (&HB8)
    DIK_RBRACKET     =  27 (&H1B)
    DIK_RCONTROL     = 157 (&H9D)
    DIK_RETURN       =  28 (&H1C)
    DIK_RIGHT        = 205 (&HCD)
    DIK_RIGHTARROW   = 205 (&HCD)
    DIK_RMENU        = 184 (&HB8)
    DIK_RSHIFT       =  54 (&H36)
    DIK_RWIN         = 220 (&HDC)
    DIK_S            =  31 (&H1F)
    DIK_SCROLL       =  70 (&H46)
    DIK_SEMICOLON    =  39 (&H27)
    DIK_SLASH        =  53 (&H35)
    DIK_SLEEP        = 223 (&HDF)
    DIK_SPACE        =  57 (&H39)
    DIK_STOP         = 149 (&H95)
    DIK_SUBTRACT     =  74 (&H4A)
    DIK_SYSRQ        = 183 (&HB7)
    DIK_T            =  20 (&H14)
    DIK_TAB          =  15
    DIK_U            =  22 (&H16)
    DIK_UNDERLINE    = 147 (&H93)
    DIK_UNLABELED    = 151 (&H97)
    DIK_UP           = 200 (&HC8)
    DIK_UPARROW      = 200 (&HC8)
    DIK_V            =  47 (&H2F)
    DIK_VOLUMEDOWN   = 174 (&HAE)
    DIK_VOLUMEUP     = 176 (&HB0)
    DIK_W            =  17 (&H11)
    DIK_WAKE         = 227 (&HE3)
    DIK_WEBBACK      = 234 (&HEA)
    DIK_WEBFAVORITES = 230 (&HE6)
    DIK_WEBFORWARD   = 233 (&HE9)
    DIK_WEBHOME      = 178 (&HB2)
    DIK_WEBREFRESH   = 231 (&HE7)
    DIK_WEBSEARCH    = 229 (&HE5)
    DIK_WEBSTOP      = 232 (&HE8)
    DIK_X            =  45 (&H2D)
    DIK_Y            =  21 (&H15)
    DIK_YEN          = 125 (&H7D)
    DIK_Z            =  44 (&H2C)
End Enum

定数

DIK_(n)
メイン キーボード上の数字キー 0 ～ 9
DIK_A�DIK_Z
メイン キーボード上の文字キー A ～ Z
DIK_ABNT_C1, DIK_ABNT_C2
ブラジル語キーボードのテンキー上
DIK_ADD
テンキー上のプラス記号 (+)
DIK_APOSTROPHE
アポストロフィ (') キー
DIK_APPS
アプリケーション キー
DIK_AT
日本語キーボード上
DIK_AX
日本語キーボード上
DIK_BACK
Backspace キー
DIK_BACKSLASH
円記号 (\) キー
DIK_BACKSPACE
Backspace キー (DIK_BACKSLASH の別名)
DIK_CALCULATOR
電卓起動専用キー
DIK_CAPITAL
CapsLock キー
DIK_CAPSLOCK
CapsLock キー (DIK_CAPITAL の別名)
DIK_CIRCUMFLEX
日本語キーボード上
DIK_COLON
日本語キーボード上
DIK_COMMA
カンマ (,) キー
DIK_CONVERT
日本語キーボード上
DIK_DECIMAL
テンキー上のピリオド (小数点)
DIK_DELETE
メイン キーボード上の Delete キー (テンキー上の Del ではない)
DIK_DIVIDE
テンキー上のスラッシュ (/)
DIK_DOWN, DIK_UP
メイン キーボード上の下矢印キー、上矢印キー (テンキー上の矢印キーではない)
DIK_DOWNARROW, UPARROW
メイン キーボード上の下矢印キー、上矢印キー (テンキー上の矢印キーではない) (DIK_DOWN および DIK_UP の別名)
DIK_END
メイン キーボード上の End キー (テンキー上の End ではない)
DIK_EQUALS
メイン キーボード上の等号
DIK_ESCAPE
Esc キー
DIK_F(n)
ファンクション キー F1 ～ F15
DIK_GRAVE
アクサン グラーブ (`) キー
DIK_HOME
メイン キーボード上の Home キー (テンキー上の Home ではない)
DIK_INSERT
メイン キーボード上の Insert キー (テンキー上の Ins ではない)
DIK_KANA
日本語キーボード上
DIK_KANJI
日本語キーボード上
DIK_LALT, DIK RALT
左右の Alt キー (DIK_LMENU および DIK_RMENU の別名)
DIK_LBRACKET, DIK_RBRACKET
左 ([) および右 (]) の角かっこキー
DIK_LCONTROL, DIK_RCONTROL
左右の Ctrl キー
DIK_LEFT, DIK_RIGHT
メイン キーボード上の左矢印キー、右矢印キー (テンキー上の矢印キーではない)
DIK LEFTARROW, DIK_RIGHTARROW
メイン キーボード上の左矢印キー、右矢印キー (テンキー上の矢印キーではない) (DIK_LEFT および DIK_RIGHT の別名)
DIK_LMENU, DIK_RMENU
左右の Alt キー
DIK_LSHIFT, DIK_RSHIFT
左右の Shift キー
DIK_LWIN, DIK_RWIN
左右の Microsoft® Windows® キー
DIK_MAIL
電子メール プログラム起動専用キー
DIK_MEDIASELECT
システムでサポートされているメディア プレーヤーの選択を表示する、メディア選択キー。
DIK_MEDIASTOP
マルチメディアの再生を停止する
DIK_MINUS
メイン キーボード上のマイナス記号 (ハイフン)
DIK_MULTIPLY
テンキー上のアスタリスク キー (*)
DIK_MUTE
サウンド出力をミュートする
DIK_MYCOMPUTER
対応している Windows システムでマイ コンピュータを起動する
DIK_NEXT
メイン キーボード上の PageDown キー (テンキー上の PgDn ではない)
DIK_NEXTTRACK
CD または DVD の次のトラックに進む
DIK_NOCONVERT
日本語キーボード上
DIK_NUMLOCK
NumLock キー
DIK_NUMPAD(n)
テンキー上の数字キー
DIK_NUMPADCOMMA
NEC PC98 テンキー上のコンマ
DIK_NUMPADENTER
テンキー上の Enter キー
DIK_NUMPADEQUALS
NEC PC98 キーボードのテンキー上の等号
DIK_NUMPADMINUS
テンキー上のマイナス記号 (DIK_SUBTRACT の別名)
DIK_NUMPADPERIOD
テンキー上の小数点 (ピリオド) (DIK_DECIMAL の別名)
DIK_NUMPADPLUS
テンキー上のプラス記号 (+) (DIK_ADD の別名)
DIK_NUMPADSLASH
テンキー上のスラッシュ (/) (DIK_DIVIDE の別名)
DIK_NUMPADSTAR
テンキー上のアスタリスク キー (*) (DIK_MULTIPLY の別名)
DIK_OEM_102
英語キーボードおよびドイツ語キーボード上
DIK_PAUSE
Pause キー
DIK_PERIOD
メイン キーボード上のピリオド (テンキー上の小数点ではない)
DIK_PGDN, DIK_PGUP
メイン キーボード上の PageDown キー、PageUp キー (テンキー上の PgDn、PgUp ではない) (DIK_NEXT および DIK_PRIOR の別名)
DIK_PLAYPAUSE
マルチメディアの再生を一時停止する
DIK_POWER
システム電源キー
DIK_PREVTRACK
CD または DVD の次のトラックを再生する
DIK_PRIOR
メイン キーボード上の PageUp キー (テンキー上の PgUp ではない)
DIK_RETURN
メイン キーボード上の Enter キー
DIK_SCROLL
ScrollLock キー
DIK_SEMICOLON
セミコロン キー
DIK_SLASH
メイン キーボード上のスラッシュ (/) (テンキー上のスラッシュではない)
DIK_SLEEP
システムをスリープ モードに移行する
DIK_SPACE
Space キー
DIK_STOP
日本語キーボード上
DIK_SUBTRACT
テンキー上のマイナス記号
DIK_SYSRQ
SysRq キー
DIK_TAB
Tab キー
DIK_UNDERLINE
日本語キーボード上
DIK_UNLABELED
日本語キーボード上
DIK_VOLUMEDOWN
サウンド出力レベルを下げる
DIK_VOLUMEUP
サウンド出力レベルを上げる
DIK_WAKE
システムをスリープ モードから復帰させる
DIK_WEBBACK
ブラウザを履歴一覧の 1 ページ前に戻す
DIK_WEBFAVORITES
Internet Explorer の [お気に入り] リスト、Windows の [Favorites] フォルダ、または Netscape のブックマーク リストを表示する。
DIK_WEBFORWARD
ブラウザに対して履歴一覧の次のページへの移動を指示する
DIK_WEBHOME
ブラウザに対してユーザーのホーム ページの読み込みを指示する
DIK_WEBREFRESH
ブラウザに対して現在のページの再読み込みを指示する
DIK_WEBSEARCH
ブラウザに対して検索エンジンの起動を指示する
DIK_WEBSTOP
ブラウザに対して現在のページの読み込み停止を指示する
DIK_YEN
日本語キーボード上

注意

この列挙の別名でない定数は、CONST_DIKEYBOARDFLAGS のメンバに対応するが、名前の先頭に付くのは DIKEYBOARD ではなく DIK であり、異なる値を持つ。


CONST_DIMAPFLAGS

DIACTION 型の lSemantic メンバに使用され、アクションをデバイス上の一致するコントロールにマップする。

これらの定数を使って、ジャンルに定義されていない仮想コントロールにアプリケーション アクションをマップできる。このようなアクションは、ジャンル固有アクションの後にマップされる。マッパーが一致するコントロールをすべてジャンル固有アクションに既にマップしていた場合、アクションはマップされないまま残される。

これらの定数にマップされたアクションには、優先度の差はない。デバイスに 1 つの x 軸があり、アクション配列が DIAXIS_ANY_1 および DIAXIS_ANY_X_1 を指定する場合、x 軸には、アクション配列の先頭に表示されるアクションがマップされる。

Enum CONST_DIMAPFLAGS
    DIAXIS_ANY_1   = -16760319 (&HFF004201)
    DIAXIS_ANY_2   = -16760318 (&HFF004202)
    DIAXIS_ANY_3   = -16760317 (&HFF004203)
    DIAXIS_ANY_4   = -16760316 (&HFF004204)
    DIAXIS_ANY_A_1 = -16530943 (&HFF03C201)
    DIAXIS_ANY_A_2 = -16530942 (&HFF03C202)
    DIAXIS_ANY_B_1 = -16498175 (&HFF044201)
    DIAXIS_ANY_B_2 = -16498174 (&HFF044202)
    DIAXIS_ANY_C_1 = -16465407 (&HFF04C201)
    DIAXIS_ANY_C_2 = -16465406 (&HFF04C202)
    DIAXIS_ANY_R_1 = -16629247 (&HFF024201)
    DIAXIS_ANY_R_2 = -16629246 (&HFF024202)
    DIAXIS_ANY_S_1 = -16432639 (&HFF054201)
    DIAXIS_ANY_S_2 = -16432638 (&HFF054202)
    DIAXIS_ANY_U_1 = -16596479 (&HFF02C201)
    DIAXIS_ANY_U_2 = -16596478 (&HFF02C202)
    DIAXIS_ANY_V_1 = -16563711 (&HFF034201)
    DIAXIS_ANY_V_2 = -16563710 (&HFF034202)
    DIAXIS_ANY_X_1 = -16727551 (&HFF00C201)
    DIAXIS_ANY_X_2 = -16727550 (&HFF00C202)
    DIAXIS_ANY_Y_1 = -16694783 (&HFF014201)
    DIAXIS_ANY_Y_2 = -16694782 (&HFF014202)
    DIAXIS_ANY_Z_1 = -16662015 (&HFF01C201)
    DIAXIS_ANY_Z_2 = -16662014 (&HFF01C202)
    DIBUTTON_ANY   = -16759808 (&HFF004400)
    DIPOV_ANY_1    = -16759295 (&HFF004601)
    DIPOV_ANY_2    = -16759294 (&HFF004602)
    DIPOV_ANY_3    = -16759293 (&HFF004603)
    DIPOV_ANY_4    = -16759292 (&HFF004604)
End Enum

定数

DIAXIS_ANY_1
任意の軸。
DIAXIS_ANY_2
任意の軸。
DIAXIS_ANY_3
任意の軸。
DIAXIS_ANY_4
任意の軸。
DIAXIS_ANY_A_1
任意のアクセラレータ。
DIAXIS_ANY_A_2
任意のアクセラレータ。
DIAXIS_ANY_B_1
任意のブレーキ。
DIAXIS_ANY_B_2
任意のブレーキ。
DIAXIS_ANY_C_1
任意のクラッチ。
DIAXIS_ANY_C_2
任意のクラッチ。
DIAXIS_ANY_R_1
任意の r 軸。
DIAXIS_ANY_R_2
任意の r 軸。
DIAXIS_ANY_S_1
任意の s 軸。
DIAXIS_ANY_S_2
任意の s 軸。
DIAXIS_ANY_U_1
任意の u 軸。
DIAXIS_ANY_U_2
任意の u 軸。
DIAXIS_ANY_V_1
任意の v 軸。
DIAXIS_ANY_V_2
任意の v 軸。
DIAXIS_ANY_X_1
任意の x 軸。
DIAXIS_ANY_X_1
任意の x 軸。
DIAXIS_ANY_Y_1
任意の y 軸。
DIAXIS_ANY_Y_1
任意の y 軸。
DIAXIS_ANY_Z_1
任意の z 軸。
DIAXIS_ANY_Z_1
任意の z 軸。
DIBUTTON_ANY
任意のボタン。
DIPOV_ANY_1
任意の視点コントローラ。
DIPOV_ANY_2
任意の視点コントローラ。
DIPOV_ANY_3
任意の視点コントローラ。
DIPOV_ANY_4
任意の視点コントローラ。


CONST_DIMOUSEFLAGS

DIACTION 型の lSemantic メンバに特定のマウス ボタンと軸を指定するために使用される。

Enum CONST_DIMOUSEFLAGS
    DIMOUSE_BUTTON0 = -2113928180 (&H8200040C)
    DIMOUSE_BUTTON1 = -2113928179 (&H8200040D)
    DIMOUSE_BUTTON2 = -2113928178 (&H8200040E)
    DIMOUSE_BUTTON3 = -2113928177 (&H8200040F)
    DIMOUSE_BUTTON4 = -2113928176 (&H82000410)
    DIMOUSE_BUTTON5 = -2113928175 (&H82000411)
    DIMOUSE_BUTTON6 = -2113928174 (&H82000412
    DIMOUSE_BUTTON7 = -2113928173 (&H82000413)
    DIMOUSE_WHEEL   = -2113928440 (&H82000308)
    DIMOUSE_XAXIS   = -2113928448 (&H82000300)
    DIMOUSE_XAXISAB = -2113928704 (&H82000200)
    DIMOUSE_YAXIS   = -2113928444 (&H82000304)
    DIMOUSE_YAXISAB = -2113928700 (&H82000204)
End Enum

定数

DIMOUSE_BUTTON(n)
ボタン 0 ～ 7。
DIMOUSE_WHEEL, DIMOUSE_XAXIS, DIMOUSE_YAXIS
相対データを返す軸。
DIMOUSE_XAXISAB, DIMOUSE_YAXISAB
絶対データを返す軸。


CONST_DIMOUSEOFS

マウス データ内のボタンと軸を識別するために使用される。定数の値は、直接データのデータ形式内のデータのオフセットである。同じ識別子がバッファリング データ パケットで使用される。

Enum CONST_DIMOUSEOFS
    DIMOFS_BUTTON0 = 12
    DIMOFS_BUTTON1 = 13
    DIMOFS_BUTTON2 = 14
    DIMOFS_BUTTON3 = 15
    DIMOFS_BUTTON4 = 16 (&H10)
    DIMOFS_BUTTON5 = 17 (&H11)
    DIMOFS_BUTTON6 = 18 (&H12)
    DIMOFS_BUTTON7 = 19 (&H13)
    DIMOFS_X       =  0
    DIMOFS_Y       =  4
    DIMOFS_Z       =  8
End Enum

定数

DIMOFS_BUTTON(n)
ボタン 0 ～ 7 のデータのオフセット。
DIMOFS_X, DIMOFS_Y, DIMOFS_Z
軸のデータのオフセット。


CONST_DINPUT

CONST_DINPUT 列挙は、Microsoft® DirectInput® 全体で使用されるさまざまな定数を格納する。

Enum CONST_DINPUT
    DIEB_NOTRIGGER               =          -1 (&HFFFFFFFF)
    DIPROPAUTOCENTER_OFF         =           0
    DIPROPAUTOCENTER_ON          =           1
    DIPROPAXISMODE_ABS           =           0
    DIPROPAXISMODE_REL           =           1
    DIPROPCALIBRATIONMODE_COOKED =           0
    DIPROPCALIBRATIONMODE_RAW    =           1
    DIPROPRANGE_NOMAX            =  2147483647 (&H7FFFFFFF)
    DIPROPRANGE_NOMIN            = -2147483648 (&H80000000)
End Enum

定数

DIEB_NOTRIGGER
DIEFFECT 型の lTriggerButton メンバに使用され、エフェクトがトリガ ボタンを持たないことを指定する。
DIPROPAUTOCENTER_OFF
ユーザーがデバイスを離しても、自動的にセンタリングを行わない。「DirectInputDevice8.SetProperty」を参照すること。
DIPROPAUTOCENTER_ON
ユーザーがデバイスを離すと、自動的にセンタリングを行う。「DirectInputDevice8.SetProperty」を参照すること。
DIPROPAXISMODE_ABS
DirectInputDevice8.GetProperty および DirectInputDevice8.SetProperty で使用され、絶対軸モードを表す。
DIPROPAXISMODE_REL
DirectInputDevice8.GetProperty および DirectInputDevice8.SetProperty で使用され、相対軸モードを表す。
DIPROPCALIBRATIONMODE_COOKED
DirectInputDevice8.SetProperty で使用され、DIPROP_CALIBRATIONMODE プロパティを設定する。
DIPROPCALIBRATIONMODE_RAW
DirectInputDevice8.SetProperty で使用され、DIPROP_CALIBRATIONMODE プロパティを設定する。
DIPROPRANGE_NOMAX
軸の範囲に上限がない場合に DirectInputDevice8.GetProperty から返される。
DIPROPRANGE_NOMIN
軸の範囲に下限がない場合に DirectInputDevice8.GetProperty から返される。


CONST_DINPUTERR

CONST_DINPUTERR 列挙は、Microsoft® DirectInput® のエラー コードを格納する。すべてのエラー コードとその定義については、「エラー コード」に記載されている。

Enum CONST_DINPUTERR
    DI_OK                         =           0
    DIERR_ACQUIRED                = -2147024726 (&H800700AA)
    DIERR_ALREADYINITIALIZED      = -2147023649 (&H800704DF)
    DIERR_BADDRIVERVER            = -2147024777 (&H80070077)
    DIERR_BETADIRECTINPUTVERSION  = -2147023743 (&H80070481)
    DIERR_DEVICEFULL              = -2147220991 (&H80040201)
    DIERR_DEVICENOTREG            = -2147221164 (&H80040154)
    DIERR_EFFECTPLAYING           = -2147220984 (&H80040208)
    DIERR_GENERIC                 = -2147467259 (&H80004005)
    DIERR_HANDLEEXISTS            = -2147024891 (&H80070005)
    DIERR_HASEFFECTS              = -2147220988 (&H80040204)
    DIERR_INCOMPLETEEFFECT        = -2147220986 (&H80040206)
    DIERR_INPUTLOST               = -2147024866 (&H8007001E)
    DIERR_INVALIDHANDLE           = -2147024890 (&H80070006)
    DIERR_INVALIDPARAM            =           5
    DIERR_MOREDATA                = -2147220990 (&H80040202)
    DIERR_NOAGGREGATION           = -2147467262 (&H80004002)
    DIERR_NOINTERFACE             =         430 (&H1AE)
    DIERR_NOTACQUIRED             = -2147024884 (&H8007000C)
    DIERR_NOTBUFFERED             = -2147220985 (&H80040207)
    DIERR_NOTDOWNLOADED           = -2147220989 (&H80040203)
    DIERR_NOTEXCLUSIVEACQUIRED    = -2147220987 (&H80040205)
    DIERR_NOTFOUND                = -2147024894 (&H80070002)
    DIERR_NOTINITIALIZED          = -2147024875 (&H80070015)
    DIERR_OBJECTNOTFOUND          = -2147024894 (&H80070002)
    DIERR_OLDDIRECTINPUTVERSION   = -2147023746 (&H8007047E)
    DIERR_OTHERAPPHASPRIO         = -2147024891 (&H80070005)
    DIERR_OUTOFMEMORY             =           7
    DIERR_READONLY                = -2147024891 (&H80070005)
    DIERR_REPORTFULL              = -2147220982 (&H8004020A)
    DIERR_UNPLUGGED               = -2147220983 (&H80040209)
    DIERR_UNSUPPORTED             =         445 (&H1BD)
    E_PENDING                     = -2147024889 (&H80070007)
End Enum

定数

DI_OK
成功。
DIERR_ACQUIRED
操作は、デバイスが取得状態の間は実行できない。
DIERR_ALREADYINITIALIZED
このオブジェクトは初期化済みである。
DIERR_BADDRIVERVER
オブジェクトは、互換性のないドライバ バージョン、あるいは不適格または不完全なドライバ コンポーネントであるために作成できなかった。
DIERR_BETADIRECTINPUTVERSION
アプリケーションは、DirectInput のサポートされていないリリース前のバージョン用に作成されたものである。
DIERR_DEVICEFULL
デバイスはフルである。
DIERR_DEVICENOTREG
デバイスまたはデバイス インスタンスが DirectInput に登録されていない。この値は、標準の COM 戻り値である REGDB_E_CLASSNOTREG に等しい。
DIERR_EFFECTPLAYING
パラメータは、メモリ内では更新されたが、デバイスにはダウンロードされなかった。デバイスが再生中のエフェクトの更新をサポートしていないためである。
DIERR_GENERIC
DirectInput サブシステムで 原因不明のエラーが発生した。この値は、標準の COM 戻り値である E_FAIL に等しい。
DIERR_HANDLEEXISTS
デバイスは、既に、自身にイベント通知の関連付けをしている。この値は、標準の COM 戻り値である E_ACCESSDENIED に等しい。
DIERR_HASEFFECTS
エフェクトがデバイスにアタッチされているため、デバイスを再初期化できない。
DIERR_INCOMPLETEEFFECT
必須情報がないので、エフェクトをダウンロードできなかった。たとえば、エフェクトに関連する軸がなかったり、タイプ固有情報が与えられていない場合。
DIERR_INPUTLOST
入力デバイスのアクセス権を失った。再取得しなければならない。
DIERR_INVALIDHANDLE
無効なウィンドウ ハンドルがメソッドに渡された。
DIERR_INVALIDPARAM
無効なパラメータが戻ってくる関数に渡されたか、オブジェクトがその関数を呼び出せる状態になかった。この値は、標準の COM 戻り値である E_INVALIDARG に等しい。
DIERR_MOREDATA
要求情報の一部がバッファに収まらなかった。
DIERR_NOAGGREGATION
オブジェクトは、集合化をサポートしない。
DIERR_NOINTERFACE
オブジェクトは、指定のインターフェイスをサポートしていない。この値は、標準の COM 戻り値である E_NOINTERFACE に等しい。
DIERR_NOTACQUIRED
操作は、デバイスが取得されない限り実行できない。
DIERR_NOTBUFFERED
デバイスは、バッファリングされていない。バッファリングを有効にするには DIPROP_BUFFERSIZE プロパティを設定する。
DIERR_NOTDOWNLOADED
エフェクトがダウンロードされていない。
DIERR_NOTEXCLUSIVEACQUIRED
操作は、デバイスが DISCL_EXCLUSIVE モードで取得されていなければ実行できない。
DIERR_NOTFOUND
要求されたオブジェクトは存在しない。
DIERR_NOTINITIALIZED
このオブジェクトは、初期化されていなかった。
DIERR_OBJECTNOTFOUND
要求されたオブジェクトは存在しない。
DIERR_OLDDIRECTINPUTVERSION
アプリケーションは、より新しいバージョンの DirectInput を必要とする。
DIERR_OTHERAPPHASPRIO
ほかのアプリケーションの優先レベルの方が高いので、この呼び出しの実行がうまくいかない。この値は、標準の COM 戻り値である E_ACCESSDENIED に等しい。このエラーは、アプリケーションのデバイスに対するアクセス権が、フォアグラウンド アクセス権であるにもかかわらず、バックグラウンドにいるときに、デバイスを取得しようとした場合に返される。
DIERR_OUTOFMEMORY
DirectInput サブシステムが呼び出しを完了するのに十分なメモリを割り当てることができなかった。この値は、標準の COM 戻り値である E_OUTOFMEMORY に等しい。
DIERR_READONLY
指定のプロパティは変更できない。この値は、標準の COM 戻り値である E_ACCESSDENIED に等しい。
DIERR_REPORTFULL
送られる情報の方が、デバイスに送ることができる情報よりも多い。
DIERR_UNPLUGGED
この操作は、デバイスが接続されていない可能性を示す。
DIERR_UNSUPPORTED
この関数呼び出しは、この時点ではサポートされない。この値は、標準の COM 戻り値である E_NOTIMPL に等しい。
E_PENDING
データは、まだ使用不可である。


CONST_DIPHFLAGS

CONST_DIPHFLAGS 列挙のメンバは、デバイス オブジェクトの識別方法を指定するために使用される。これらのメンバは、DirectInputDevice8.GetObjectInfo メソッドのほか、DIPROPLONG 型と DIPROPRANGE 型で使用される。

Enum CONST_DIPHFLAGS
    DIPH_BYID     = 2
    DIPH_BYOFFSET = 1
    DIPH_BYUSAGE  = 3
    DIPH_DEVICE   = 0
End Enum

定数

DIPH_BYID
デバイス オブジェクトは、DirectInputDeviceObjectInstance.GetType メソッドの戻り値から取得されるインスタンス識別子で識別される。
DIPH_BYOFFSET
デバイス オブジェクトは、アクセスする情報が所属するオブジェクトの現在のデータ形式に対するオフセットで識別される。
DIPH_BYUSAGE
デバイス オブジェクトは、パックされた形式の HID 使用状況ページと使用状況の値で識別される。
DIPH_DEVICE
プロパティは、特定のオブジェクトではなくデバイス全体に適用される。


CONST_DISCLFLAGS

CONST_DISCLFLAGS 列挙は、DirectInputDevice8.SetCooperativeLevel メソッドの flags パラメータに使用され、デバイスが、そのデバイスのほかのインスタンスおよびシステムの残りの部分と通信する方法を決定する。

Enum CONST_DISCLFLAGS
    DISCL_BACKGROUND   =  8
    DISCL_EXCLUSIVE    =  1
    DISCL_FOREGROUND   =  4
    DISCL_NONEXCLUSIVE =  2
    DISCL_NOWINKEY     = 16 (&H10)
End Enum

定数

DISCL_BACKGROUND
アプリケーションは、バックグラウンド アクセス権を要求する。バックグラウンド アクセス権が許可されると、割り当てられたウィンドウがアクティブ ウィンドウでない場合でも、いつでもデバイスを取得できる。
DISCL_EXCLUSIVE
アプリケーションは、排他アクセス権を要求する。排他アクセス権が付与されると、デバイスが取得されている間、デバイスのほかのインスタンスは、そのデバイスの排他アクセス権を取得できない。ただし、別のアプリケーションが排他アクセス権を取得している場合でも、デバイスの非排他アクセス権は常に認められる。

アプリケーションがマウス デバイスやキーボード デバイスを取得すると、ユーザーはウィンドウ メニューを使用したり、ウィンドウを移動したり、ウィンドウのサイズを変更したりすることはできなくなる。

DISCL_FOREGROUND
アプリケーションはフォアグラウンド アクセス権を要求する。フォアグラウンド アクセス権が付与されると、割り当てられたウィンドウがバックグラウンドに移動するときに、デバイスは自動的に解放される。
DISCL_NONEXCLUSIVE
アプリケーションは、排他アクセス権を要求する。デバイスに対するアクセス権は、同じデバイスにアクセスしているほかのアプリケーションの妨げにならない。
DISCL_NOWINKEY
ユーザーが不注意でアプリケーションを終了することのないように、Microsoft® Windows® キーを無効にする。この値を DISCL_NONEXCLUSIVE と組み合わせることができる。排他モードでは、Windows キーは常に無効である。ただし、デフォルトのアクション マッピング UI が表示されている間は DISCL_NOWINKEY フラグは無効であり、また、デフォルトのアクション マッピング UI が存在している間は Windows キーは通常どおり機能する。

アプリケーションは、DISCL_FOREGROUND または DISCL_BACKGROUND のどちらか一方を指定しなければならない。両方指定することも、まったく指定しないこともエラーとなる。同様に、アプリケーションは、DISCL_EXCLUSIVE または DISCL_NONEXCLUSIVE のどちらか一方を指定しなければならない。


CONST_DISDDFLAGS

CONST_DISDDFLAGS 列挙のメンバは、DirectInputDevice8.SendDeviceData メソッドに渡される。

Enum CONST_DISDDFLAGS
    DISDD_CONTINUE = 1
    DISDD_DEFAULT  = 0
End Enum

定数

DISDD_CONTINUE
データは既存のデータを上書きする。詳細については、DirectInputDevice8.SendDeviceData メソッドの「注意」を参照すること。
DISDD_DEFAULT
データは既存のデータを上書きしない。


CONST_DISFFCFLAGS

CONST_DISFFCFLAGS 列挙のメンバは、DirectInputDevice8.SendForceFeedbackCommand メソッドでコマンドを指定するために使用される。

Enum CONST_DISFFCFLAGS
    DISFFC_CONTINUE        =  8
    DISFFC_PAUSE           =  4
    DISFFC_RESET           =  1
    DISFFC_SETACTUATORSOFF = 32 (&H20)
    DISFFC_SETACTUATORSON  = 16 (&H10)
    DISFFC_STOPALL         =  2
End Enum

定数

DISFFC_CONTINUE
中断されたすべてのアクティブなエフェクトの再生を継続する。デバイスが中断状態にないときにこのコマンドを送信すると、エラーになる。
DISFFC_PAUSE
すべてのアクティブ エフェクトの再生を中断する。このコマンドはエフェクトのクロックも停止するので、再開すると、エフェクトは継続時間を満了するまで再生が続行される。

デバイスが中断状態にある間は、新しいエフェクトを開始したり、既存のエフェクトを変更したりすることはできない。そのような操作を行うと、これ以降の DISFFC_CONTINUE コマンドが正常に機能しなくなることがある。

中断を破棄してすべてのエフェクトを停止するには、DISFFC_STOPALL または DISFCC_RESET コマンドを使用する。

DISFFC_RESET
デバイスのフォース フィードバック システムを始動状態にする。すべてのエフェクトはデバイスから削除され、有効でなくなる。これらのエフェクトを再び使用するには、再生成しなければならない。デバイスのアクチュエータは無効である。
DISFFC_SETACTUATORSOFF
デバイスのフォース フィードバック アクチュエータを無効にする。アクチュエータがオフの間も、エフェクトは引き続き再生されるが、デバイスはそれを無視する。音楽再生デバイスにたとえると、エフェクトは一時停止 (ポーズ) ではなく、消音 (ミュート) された状態である。
DISFFC_SETACTUATORSON
デバイスのフォース フィードバック アクチュエータを有効にする。
DISFFC_STOPALL
すべてのアクティブなエフェクトの再生を停止する。アクティブなエフェクトはすべてリセットされるが、デバイスには保存されており、引き続き有効である。デバイスが中断されている場合、その状態は失われる。

このコマンドは、再生中のエフェクトごとに DirectInputEffect.Stop メソッドを呼び出すことに等しい。


CONST_DIVOICEFLAGS

DIACTION 型の lSemantic メンバに音声デバイス オブジェクトを指定するために使用される。

Enum CONST_DIVOICEFLAGS
    DIVOICE_ALL          = -2097150966 (&H8300040A)
    DIVOICE_CHANNEL1     = -2097150975 (&H83000401)
    DIVOICE_CHANNEL2     = -2097150974 (&H83000402)
    DIVOICE_CHANNEL3     = -2097150973 (&H83000403)
    DIVOICE_CHANNEL4     = -2097150972 (&H83000404)
    DIVOICE_CHANNEL5     = -2097150971 (&H83000405)
    DIVOICE_CHANNEL6     = -2097150970 (&H83000406)
    DIVOICE_CHANNEL7     = -2097150969 (&H83000407)
    DIVOICE_CHANNEL8     = -2097150968 (&H83000408)
    DIVOICE_PLAYBACKMUTE = -2097150964 (&H8300040C)
    DIVOICE_RECORDMUTE   = -2097150965 (&H8300040B)
    DIVOICE_TEAM         = -2097150967 (&H83000409)
    DIVOICE_TRANSMIT     = -2097150963 (&H8300040D)
    DIVOICE_VOICECOMMAND = -2097150960 (&H83000410)
End Enum
DIVOICE_ALL
音声入力をすべてのチャネルにある要素を全要素にコピーする。
DIVOICE_CHANNEL(n)
チャネル 1 ～ 8 に個別にある要素を全要素にコピーする。
DIVOICE_PLAYBACKMUTE
音声のある要素を全要素にコピーすることをミュートする
DIVOICE_RECORDMUTE
録音をミュートする。
DIVOICE_TEAM
チームのメンバに音声のみをある要素を全要素にコピーする。
DIVOICE_TRANSMIT
送信のある要素を全要素にコピーする。
DIVOICE_VOICECOMMAND
ある要素を全要素にコピーするデータではなく音声入力を音声コマンドとして受け付ける。


キーボード キー

ここでは、次の内容について説明する。

  • キーボード デバイス定数
  • DirectInput と日本語キーボード


キーボード デバイス定数

CONST_DIKEYFLAGS 列挙のメンバは、キーボード デバイスのデータ パケット (256 バイト配列) 内でのオフセットを表す。指定のオフセット位置のデータは、キーボード キーに関連付けられている。

標準キーボード デバイス定数は、以下のとおりである (データ オフセットの昇順)。

アクション マッピングで使用される CONST_DIKEYBOARDFLAGS 列挙にも、次の表のキー定数が含まれる。アクション マッピング用の定数の場合、名前の先頭は "DIK" ではなく "DIKEYBOARD" となる。

定数 | メモ
DIK_ESCAPE |
DIK_1 | メイン キーボード上
DIK_2 | メイン キーボード上
DIK_3 | メイン キーボード上
DIK_4 | メイン キーボード上
DIK_5 | メイン キーボード上
DIK_6 | メイン キーボード上
DIK_7 | メイン キーボード上
DIK_8 | メイン キーボード上
DIK_9 | メイン キーボード上
DIK_0 | メイン キーボード上
DIK_MINUS | メイン キーボード上
DIK_EQUALS | メイン キーボード上
DIK_BACK | BaackSpace キー
DIK_TAB |
DIK_Q |
DIK_W |
DIK_E |
DIK_R |
DIK_T |
DIK_Y |
DIK_U |
DIK_I |
DIK_O |
DIK_P |
DIK_LBRACKET | 左角かっこ。
DIK_RBRACKET | 右角かっこ
DIK_RETURN | メイン キーボード上の Enter キー
DIK_LCONTROL | 左 Ctrl キー
DIK_A |
DIK_S |
DIK_D |
DIK_F |
DIK_G |
DIK_H |
DIK_J |
DIK_K |
DIK_L |
DIK_SEMICOLON |
DIK_APOSTROPHE |
DIK_GRAVE | アクサン グラーブ (`) キー
DIK_LSHIFT | 左 Shift キー
DIK_BACKSLASH |
DIK_Z |
DIK_X |
DIK_C |
DIK_V |
DIK_B |
DIK_N |
DIK_M |
DIK_COMMA |
DIK_PERIOD | メイン キーボード上
DIK_SLASH | メイン キーボード上のスラッシュ
DIK_RSHIFT | 右 Shift キー
DIK_MULTIPLY | テンキー上のアスタリスク キー
DIK_LMENU | 左 Alt キー
DIK_SPACE | Space キー
DIK_CAPITAL | CapsLock
DIK_F1 |
DIK_F2 |
DIK_F3 |
DIK_F4 |
DIK_F5 |
DIK_F6 |
DIK_F7 |
DIK_F8 |
DIK_F9 |
DIK_F10 |
DIK_NUMLOCK |
DIK_SCROLL | ScrollLock
DIK_NUMPAD7 |
DIK_NUMPAD8 |
DIK_NUMPAD9 |
DIK_SUBTRACT | テンキー上のマイナス記号
DIK_NUMPAD4 |
DIK_NUMPAD5 |
DIK_NUMPAD6 |
DIK_ADD | テンキー上のプラス記号
DIK_NUMPAD1 |
DIK_NUMPAD2 |
DIK_NUMPAD3 |
DIK_NUMPAD0 |
DIK_DECIMAL | テンキー上のピリオド (小数点)
DIK_OEM_102 | 英語キーボードおよびドイツ語キーボード上
DIK_F11 |
DIK_F12 |
DIK_F13 |
DIK_F14 |
DIK_F15 |
DIK_KANA | 日本語キーボード上
DIK_ABNT_C1 | ブラジル語キーボードのテンキー上
DIK_CONVERT | 日本語キーボード上
DIK_NOCONVERT | 日本語キーボード上
DIK_YEN | 日本語キーボード上
DIK_ABNT_C2 | ブラジル語キーボードのテンキー上
DIK_NUMPADEQUALS | テンキー上 (NEC PC98)
DIK_PREVTRACK | 前のトラック、日本語キーボードのサーカムフレックス
DIK_AT | 日本語キーボード上
DIK_COLON | 日本語キーボード上
DIK_UNDERLINE | 日本語キーボード上
DIK_KANJI | 日本語キーボード上
DIK_STOP | 日本語キーボード上
DIK_AX | 日本語キーボード上
DIK_UNLABELED | 日本語キーボード上
DIK_NEXTTRACK | 次のトラック
DIK_NUMPADENTER |
DIK_RCONTROL | 右 Ctrl キー
DIK_MUTE |
DIK_CALCULATOR |
DIK_PLAYPAUSE |
DIK_MEDIASTOP |
DIK_VOLUMEDOWN |
DIK_VOLUMEUP |
DIK_WEBHOME |
DIK_NUMPADCOMMA | NEC PC98 テンキー上のコンマ
DIK_DIVIDE | テンキー上のスラッシュ
DIK_SYSRQ |
DIK_RMENU | 右 Alt キー
DIK_PAUSE |
DIK_HOME
DIK_UP | 上矢印キー
DIK_PRIOR | PageUp キー
DIK_LEFT | 左矢印キー
DIK_RIGHT | 右矢印キー
DIK_END |
DIK_DOWN | 下矢印キー
DIK_NEXT | PageDown キー
DIK_INSERT |
DIK_DELETE |
DIK_LWIN | 左 Microsoft® Windows® キー
DIK_RWIN | 右 Windows キー
DIK_APPS | アプリケーション キー
DIK_POWER |
DIK_SLEEP |
DIK_WAKE |
DIK_WEBSEARCH |
DIK_WEBFAVORITES |
DIK_WEBREFRESH |
DIK_WEBSTOP |
DIK_WEBFORWARD |
DIK_WEBBACK |
DIK_MYCOMPUTER |
DIK_MAIL |
DIK_MEDIASELECT |

日本語キーボードについては、「DirectInput と日本語キーボード」を参照すること。


DirectInput と日本語キーボード

以下に、標準の US キーボードにはないが、日本語キーボードで使用可能な拡張キーと、US キーボードでは使用可能であるが、多くの日本語キーボードにはないキーの一覧を示す。

Microsoft® Windows® 2000 上、およびその他のオペレーティング システムを使用している一部のキーボード (NEC PC-98 など) では、DIK_CAPSLOCK、DIK_KANJI、および DIK_KANA キーはトグル ボタンであり、プッシュ ボタンではない。これらのキーは、最初に押されたときにダウン イベントを生成し、2 回目に押されたときにアップ イベントを生成する。

日本語キーボード | 拡張キー | 欠けるキー
DOS/V 106, NEC PC-98 106 | DIK_AT, DIK_CIRCUMFLEX, DIK_COLON, DIK_CONVERT, DIK_KANA, DIK_KANJI, DIK_NOCONVERT, DIK_YEN | DIK_APOSTROPHE, DIK_EQUALS, DIK_GRAVE
NEC PC-98 | DIK_AT, DIK_CIRCUMFLEX, DIK_COLON, DIK_F13, DIK_F14, DIK_F15, DIK_KANA, DIK_KANJI, DIK_NOCONVERT, DIK_NUMPADCOMMA, DIK_NUMPADEQUALS, DIK_STOP, DIK_UNDERLINE, DIK_YEN | DIK_APOSTROPHE, DIK_BACKSLASH, DIK_EQUALS, DIK_GRAVE, DIK_NUMLOCK, DIK_NUMPADENTER, DIK_RCONTROL, DIK_RMENU, DIK_RSHIFT, DIK_SCROLL
AX | DIK_AX, DIK_CONVERT, DIK_KANJI, DIK_NOCONVERT, DIK_YEN | DIK_RCONTROL, DIK_RMENU
J-3100 | DIK_KANA, DIK_KANJI, DIK_NOLABEL, DIK_YEN | DIK_RCONTROL, DIK_RMENU


アクション マッピング定数

ここでは、アプリケーションのジャンルと各ジャンル内のアクションにマップされたコントロール用に、CONST_DIGENRE 列挙に定義された定数のリファレンスを提供する。

DIAXIS_FIGHTINGH_MOVE などのコントロール定数は、DIACTION 構造体の ActionName メンバで使用され、コントロールをアプリケーション内のアクションに関連付ける。

DIVIRTUAL_FIGHTING_HAND2HAND などのジャンル定数は、DIACTIONFORMAT 構造体の lGenre メンバで使用される。

アクション マッピング定数は、次のカテゴリのアプリケーション ジャンル用に提供されている。

  • アクション ジャンル
  • アーケード ジャンル
  • CAD ジャンル
  • コントロール ジャンル
  • ドライビング ジャンル
  • フライト ジャンル
  • スポーツ ジャンル
  • ストラテジ ジャンル

DIACTION 構造体の ActionName メンバを使って、アクションを仮想コントロールではなく特定のデバイス オブジェクトにマップすることができる。デバイス オブジェクト定数は、次のカテゴリに提供されている。

  • キーボード マッピング定数
  • マウス マッピング定数
  • DirectPlay 音声マッピング定数
  • 任意コントロール定数


アクション ジャンル

次のジャンルには、戦闘ゲームやアクション ゲーム用のコントロールが含まれる。

  • 格闘
  • シューティング
  • 非対面型のアクション


格闘

DIVIRTUAL_FIGHTING_HAND2HAND ジャンルには、銃を使用しない対面型の格闘ゲームのコントロールが含まれる。

優先順位 1 のコントロール
DIAXIS_FIGHTINGH_LATERAL
DIAXIS_FIGHTINGH_MOVE
DIBUTTON_FIGHTINGH_BLOCK
DIBUTTON_FIGHTINGH_CROUCH
DIBUTTON_FIGHTINGH_JUMP
DIBUTTON_FIGHTINGH_KICK
DIBUTTON_FIGHTINGH_MENU
DIBUTTON_FIGHTINGH_PUNCH
DIBUTTON_FIGHTINGH_SPECIAL1
DIBUTTON_FIGHTINGH_SPECIAL2

優先順位 2 のコントロール
DIAXIS_FIGHTINGH_ROTATE
DIBUTTON_FIGHTINGH_BACKWARD_LINK
DIBUTTON_FIGHTINGH_DEVICE
DIBUTTON_FIGHTINGH_DISPLAY
DIBUTTON_FIGHTINGH_DODGE
DIBUTTON_FIGHTINGH_FORWARD_LINK
DIBUTTON_FIGHTINGH_LEFT_LINK
DIBUTTON_FIGHTINGH_PAUSE
DIBUTTON_FIGHTINGH_RIGHT_LINK
DIBUTTON_FIGHTINGH_SELECT
DIHATSWITCH_FIGHTINGH_SLIDE


シューティング

DIVIRTUAL_FIGHTING_FPS ジャンルには、銃を使用する対面型の戦闘ゲームのコントロールが含まれる。

優先順位 1 のコントロール
DIAXIS_FPS_LOOKUPDOWN
DIAXIS_FPS_MOVE
DIAXIS_FPS_ROTATE
DIBUTTON_FPS_APPLY
DIBUTTON_FPS_CROUCH
DIBUTTON_FPS_FIRE
DIBUTTON_FPS_JUMP
DIBUTTON_FPS_MENU
DIBUTTON_FPS_SELECT
DIBUTTON_FPS_STRAFE
DIBUTTON_FPS_WEAPONS

優先順位 2 のコントロール
DIAXIS_FPS_SIDESTEP
DIBUTTON_FPS_BACKWARD_LINK
DIBUTTON_FPS_DEVICE
DIBUTTON_FPS_DISPLAY
DIBUTTON_FPS_DODGE
DIBUTTON_FPS_FIRESECONDARY
DIBUTTON_FPS_FORWARD_LINK
DIBUTTON_FPS_GLANCE_DOWN_LINK
DIBUTTON_FPS_GLANCE_UP_LINK
DIBUTTON_FPS_GLANCEL
DIBUTTON_FPS_GLANCER
DIBUTTON_FPS_PAUSE
DIBUTTON_FPS_ROTATE_LEFT_LINK
DIBUTTON_FPS_ROTATE_RIGHT_LINK
DIHATSWITCH_FPS_GLANCE


非対面型のアクション

DIVIRTUAL_FIGHTING_THIRDPERSON ジャンルには、非対面型のアクション ゲームのコントロールが含まれる。

優先順位 1 のコントロール
DIAXIS_TPS_MOVE
DIAXIS_TPS_TURN
DIBUTTON_TPS_ACTION
DIBUTTON_TPS_JUMP
DIBUTTON_TPS_MENU
DIBUTTON_TPS_RUN
DIBUTTON_TPS_SELECT
DIBUTTON_TPS_USE

優先順位 2 のコントロール
DIAXIS_TPS_STEP
DIBUTTON_TPS_BACKWARD_LINK
DIBUTTON_TPS_DEVICE
DIBUTTON_TPS_DODGE
DIBUTTON_TPS_FORWARD_LINK
DIBUTTON_TPS_GLANCE_DOWN_LINK
DIBUTTON_TPS_GLANCE_LEFT_LINK
DIBUTTON_TPS_GLANCE_RIGHT_LINK
DIBUTTON_TPS_GLANCE_UP_LINK
DIBUTTON_TPS_INVENTORY
DIBUTTON_TPS_PAUSE
DIBUTTON_TPS_STEPLEFT
DIBUTTON_TPS_STEPRIGHT
DIBUTTON_TPS_TURN_LEFT_LINK
DIBUTTON_TPS_TURN_RIGHT_LINK
DIBUTTON_TPS_VIEW
DIHATSWITCH_TPS_GLANCE


アーケード ジャンル

次のジャンルには、危険な状況の中でキャラクタを動かすことを目的とする、アーケード型ゲームのコントロールが含まれる。

  • プラットフォーム
  • サイドツーサイド


プラットフォーム

DIVIRTUAL_ARCADE_PLATFORM ジャンルには、アーケード型ゲームのコントロールが含まれる。

優先順位 1 のコントロール
DIAXIS_ARCADEP_LATERAL
DIAXIS_ARCADEP_MOVE
DIBUTTON_ARCADEP_CROUCH
DIBUTTON_ARCADEP_FIRE
DIBUTTON_ARCADEP_JUMP
DIBUTTON_ARCADEP_MENU
DIBUTTON_ARCADEP_SELECT
DIBUTTON_ARCADEP_SPECIAL

優先順位 2 のコントロール
DIBUTTON_ARCADEP_BACK_LINK
DIBUTTON_ARCADEP_DEVICE
DIBUTTON_ARCADEP_FIRESECONDARY
DIBUTTON_ARCADEP_FORWARD_LINK
DIBUTTON_ARCADEP_LEFT_LINK
DIBUTTON_ARCADEP_PAUSE
DIBUTTON_ARCADEP_RIGHT_LINK
DIBUTTON_ARCADEP_VIEW_DOWN_LINK
DIBUTTON_ARCADEP_VIEW_LEFT_LINK
DIBUTTON_ARCADEP_VIEW_RIGHT_LINK
DIBUTTON_ARCADEP_VIEW_UP_LINK
DIHATSWITCH_ARCADEP_VIEW


サイドツーサイド

DIVIRTUAL_ARCADE_SIDE2SIDE ジャンルには、アーケード型 2 次元ゲームのコントロールが含まれる。

優先順位 1 のコントロール
DIAXIS_ARCADES_LATERAL
DIAXIS_ARCADES_MOVE
DIBUTTON_ARCADES_ATTACK
DIBUTTON_ARCADES_CARRY
DIBUTTON_ARCADES_MENU
DIBUTTON_ARCADES_SELECT
DIBUTTON_ARCADES_SPECIAL
DIBUTTON_ARCADES_THROW

優先順位 2 のコントロール
DIBUTTON_ARCADES_BACK_LINK
DIBUTTON_ARCADES_DEVICE
DIBUTTON_ARCADES_FORWARD_LINK
DIBUTTON_ARCADES_LEFT_LINK
DIBUTTON_ARCADES_PAUSE
DIBUTTON_ARCADES_RIGHT_LINK
DIBUTTON_ARCADES_VIEW_DOWN_LINK
DIBUTTON_ARCADES_VIEW_LEFT_LINK
DIBUTTON_ARCADES_VIEW_RIGHT_LINK
DIBUTTON_ARCADES_VIEW_UP_LINK
DIHATSWITCH_ARCADES_VIEW


CAD ジャンル

次のジャンルには、CAD (Computer-Assisted Drafting) アプリケーション用のコントロールが含まれる。

  • 2-D オブジェクト
  • 3-D モデル
  • 3-D ナビゲーション
  • 3-D オブジェクト


2-D オブジェクト

DIVIRTUAL_CAD_2DCONTROL ジャンルには、2 次元の設計環境でオブジェクトの選択、移動を行うためのコントロールが含まれる。

優先順位 1 のコントロール
DIAXIS_2DCONTROL_LATERAL
DIAXIS_2DCONTROL_MOVE
DIAXIS_2DCONTROL_INOUT
DIBUTTON_2DCONTROL_MENU
DIBUTTON_2DCONTROL_SELECT
DIBUTTON_2DCONTROL_SPECIAL
DIBUTTON_2DCONTROL_SPECIAL1
DIBUTTON_2DCONTROL_SPECIAL2

優先順位 2 のコントロール
DIAXIS_2DCONTROL_ROTATEZ
DIBUTTON_2DCONTROL_DEVICE
DIBUTTON_2DCONTROL_DISPLAY
DIBUTTON_2DCONTROL_PAUSE
DIHATSWITCH_2DCONTROL_HATSWITCH


3-D モデル

DIVIRTUAL_CAD_MODEL ジャンルには、3 次元オブジェクト モデリング用のコントロールが含まれる。

優先順位 1 のコントロール
DIAXIS_CADM_LATERAL
DIAXIS_CADM_MOVE
DIAXIS_CADM_INOUT
DIBUTTON_CADM_MENU
DIBUTTON_CADM_SELECT
DIBUTTON_CADM_SPECIAL
DIBUTTON_CADM_SPECIAL1
DIBUTTON_CADM_SPECIAL2

優先順位 2 のコントロール
DIAXIS_CADM_ROTATEX
DIAXIS_CADM_ROTATEY
DIAXIS_CADM_ROTATEZ
DIBUTTON_CADM_DEVICE
DIBUTTON_CADM_DISPLAY
DIBUTTON_CADM_PAUSE
DIHATSWITCH_CADM_HATSWITCH


3-D ナビゲーション

DIVIRTUAL_CAD_FLYBY ジャンルには、3 次元環境のフライスルー ナビゲーション用のコントロールが含まれる。

優先順位 1 のコントロール
DIAXIS_CADF_LATERAL
DIAXIS_CADF_MOVE
DIAXIS_CADF_INOUT
DIBUTTON_CADF_MENU
DIBUTTON_CADF_SELECT
DIBUTTON_CADF_SPECIAL
DIBUTTON_CADF_SPECIAL1
DIBUTTON_CADF_SPECIAL2

優先順位 2 のコントロール
DIAXIS_CADF_ROTATEX
DIAXIS_CADF_ROTATEY
DIAXIS_CADF_ROTATEZ
DIBUTTON_CADF_DEVICE
DIBUTTON_CADF_DISPLAY
DIBUTTON_CADF_PAUSE
DIHATSWITCH_CADF_HATSWITCH


3-D オブジェクト

DIVIRTUAL_CAD_3DCONTROL ジャンルには、3 次元の設計環境でオブジェクトの選択、移動を行うためのコントロールが含まれる。

優先順位 1 のコントロール
DIAXIS_3DCONTROL_LATERAL
DIAXIS_3DCONTROL_MOVE
DIAXIS_3DCONTROL_INOUT
DIBUTTON_3DCONTROL_MENU
DIBUTTON_3DCONTROL_SELECT
DIBUTTON_3DCONTROL_SPECIAL
DIBUTTON_3DCONTROL_SPECIAL1
DIBUTTON_3DCONTROL_SPECIAL2

優先順位 2 のコントロール
DIAXIS_3DCONTROL_ROTATEX
DIAXIS_3DCONTROL_ROTATEY
DIAXIS_3DCONTROL_ROTATEZ
DIBUTTON_3DCONTROL_DEVICE
DIBUTTON_3DCONTROL_DISPLAY
DIBUTTON_3DCONTROL_PAUSE
DIHATSWITCH_3DCONTROL_HATSWITCH


コントロール ジャンル

次のジャンルには、Web ブラウザとリモートコントロール デバイスで使用されるコントロールが含まれる。

  • ブラウザ
  • リモート コントロール


ブラウザ

DIVIRTUAL_BROWSER_CONTROL ジャンルには、Web ブラウザ用のコントロールが含まれる。

優先順位 1 のコントロール
DIAXIS_BROWSER_LATERAL
DIAXIS_BROWSER_MOVE
DIAXIS_BROWSER_VIEW
DIBUTTON_BROWSER_MENU
DIBUTTON_BROWSER_REFRESH
DIBUTTON_BROWSER_SELECT

優先順位 2 のコントロール
DIBUTTON_BROWSER_DEVICE
DIBUTTON_BROWSER_FAVORITES
DIBUTTON_BROWSER_HISTORY
DIBUTTON_BROWSER_HOME
DIBUTTON_BROWSER_NEXT
DIBUTTON_BROWSER_PAUSE
DIBUTTON_BROWSER_PREVIOUS
DIBUTTON_BROWSER_PRINT
DIBUTTON_BROWSER_SEARCH
DIBUTTON_BROWSER_STOP


リモート コントロール

DIVIRTUAL_REMOTE_CONTROL ジャンルには、メディア プレーヤーなどの装置で使用されるリモート コントロール デバイス用のコントロールが含まれる。

優先順位 1 のコントロール
DIAXIS_REMOTE_SLIDER
DIBUTTON_REMOTE_CHANGE
DIBUTTON_REMOTE_CUE
DIBUTTON_REMOTE_MENU
DIBUTTON_REMOTE_MUTE
DIBUTTON_REMOTE_PLAY
DIBUTTON_REMOTE_RECORD
DIBUTTON_REMOTE_REVIEW
DIBUTTON_REMOTE_SELECT

優先順位 2 のコントロール
DIAXIS_REMOTE_SLIDER2
DIBUTTON_REMOTE_ADJUST
DIBUTTON_REMOTE_CABLE
DIBUTTON_REMOTE_CD
DIBUTTON_REMOTE_DEVICE
DIBUTTON_REMOTE_DIGIT0
DIBUTTON_REMOTE_DIGIT1
DIBUTTON_REMOTE_DIGIT2
DIBUTTON_REMOTE_DIGIT3
DIBUTTON_REMOTE_DIGIT4
DIBUTTON_REMOTE_DIGIT5
DIBUTTON_REMOTE_DIGIT6
DIBUTTON_REMOTE_DIGIT7
DIBUTTON_REMOTE_DIGIT8
DIBUTTON_REMOTE_DIGIT9
DIBUTTON_REMOTE_DVD
DIBUTTON_REMOTE_PAUSE
DIBUTTON_REMOTE_TUNER
DIBUTTON_REMOTE_TV
DIBUTTON_REMOTE_VCR


ドライビング ジャンル

次のジャンルは、プレーヤーがレーシングや戦闘で車を制御するゲームで使用される。

  • コンバット レーシング
  • ロボット戦闘
  • レーシング
  • タンク


コンバット レーシング

DIVIRTUAL_DRIVING_COMBAT ジャンルには、戦闘のある乗り物レース ゲーム用のコントロールが含まれる。

優先順位 1 のコントロール
DIAXIS_DRIVINGC_ACCELERATE
DIAXIS_DRIVINGC_BRAKE
DIAXIS_DRIVINGC_STEER
DIBUTTON_DRIVINGC_FIRE
DIBUTTON_DRIVINGC_MENU
DIBUTTON_DRIVINGC_TARGET
DIBUTTON_DRIVINGC_WEAPONS

優先順位 2 のコントロール
DIBUTTON_DRIVINGC_ACCELERATE-LINK
DIBUTTON_DRIVINGC_AIDS
DIBUTTON_DRIVINGC_BRAKE
DIBUTTON_DRIVINGC_DASHBOARD
DIBUTTON_DRIVINGC_DEVICE
DIBUTTON_DRIVINGC_FIRESECONDARY
DIBUTTON_DRIVINGC_GLANCE_LEFT_LINK
DIBUTTON_DRIVINGC_GLANCE_RIGHT_LINK
DIBUTTON_DRIVINGC_PAUSE
DIBUTTON_DRIVINGC_SHIFTDOWN
DIBUTTON_DRIVINGC_SHIFTUP
DIBUTTON_DRIVINGC_STEER_LEFT_LINK
DIBUTTON_DRIVINGC_STEER_RIGHT_LINK
DIHATSWITCH_DRIVINGC_GLANCE


ロボット戦闘

DIVIRTUAL_DRIVING_MECHA ジャンルには、ロボット戦争ゲームにおける歩行ロボット (メック) 用のコントロールが含まれる。

優先順位 1 のコントロール
DIAXIS_MECHA_ROTATE
DIAXIS_MECHA_STEER
DIAXIS_MECHA_THROTTLE
DIAXIS_MECHA_TORSO
DIBUTTON_MECHA_FIRE
DIBUTTON_MECHA_JUMP
DIBUTTON_MECHA_MENU
DIBUTTON_MECHA_REVERSE
DIBUTTON_MECHA_TARGET
DIBUTTON_MECHA_WEAPONS
DIBUTTON_MECHA_ZOOM

優先順位 2 のコントロール
DIBUTTON_MECHA_BACK_LINK
DIBUTTON_MECHA_CENTER
DIBUTTON_MECHA_DEVICE
DIBUTTON_MECHA_FASTER_LINK
DIBUTTON_MECHA_FIRESECONDARY
DIBUTTON_MECHA_FORWARD_LINK
DIBUTTON_MECHA_LEFT_LINK
DIBUTTON_MECHA_PAUSE
DIBUTTON_MECHA_RIGHT_LINK
DIBUTTON_MECHA_ROTATE_LEFT_LINK
DIBUTTON_MECHA_ROTATE_RIGHT_LINK
DIBUTTON_MECHA_SLOWER_LINK
DIBUTTON_MECHA_VIEW
DIHATSWITCH_MECHA_GLANCE


レーシング

DIVIRTUAL_DRIVING_RACE ジャンルには、戦闘のない自動車レース ゲーム用のコントロールが含まれる。

優先順位 1 のコントロール
DIAXIS_DRIVINGR_ACCELERATE
DIAXIS_DRIVINGR_BRAKE
DIAXIS_DRIVINGR_STEER
DIBUTTON_DRIVINGR_MENU
DIBUTTON_DRIVINGR_SHIFTDOWN
DIBUTTON_DRIVINGR_SHIFTUP
DIBUTTON_DRIVINGR_VIEW

優先順位 2 のコントロール
DIAXIS_DRIVINGR_ACCEL_AND_BRAKE
DIBUTTON_DRIVINGR_ACCELERATE_LINK
DIBUTTON_DRIVINGR_AIDS
DIBUTTON_DRIVINGR_BOOST
DIBUTTON_DRIVINGR_BRAKE
DIBUTTON_DRIVINGR_DASHBOARD
DIBUTTON_DRIVINGR_DEVICE
DIBUTTON_DRIVINGR_GLANCE_LEFT_LINK
DIBUTTON_DRIVINGR_GLANCE_RIGHT_LINK
DIBUTTON_DRIVINGR_MAP
DIBUTTON_DRIVINGR_PAUSE
DIBUTTON_DRIVINGR_PIT
DIBUTTON_DRIVINGR_STEER_LEFT_LINK
DIBUTTON_DRIVINGR_STEER_RIGHT_LINK
DIHATSWITCH_DRIVINGR_GLANCE


タンク

DIVIRTUAL_DRIVING_TANK ジャンルには、戦車シミュレーション用のコントロールが含まれる。

優先順位 1 のコントロール
DIAXIS_DRIVINGT_ACCELERATE
DIAXIS_DRIVINGT_BARREL
DIAXIS_DRIVINGT_STEER
DIBUTTON_DRIVINGT_FIRE
DIBUTTON_DRIVINGT_MENU
DIBUTTON_DRIVINGT_TARGET
DIBUTTON_DRIVINGT_WEAPONS

優先順位 2 のコントロール
DIAXIS_DRIVINGT_ACCEL_AND_BRAKE
DIAXIS_DRIVINGT_BRAKE
DIAXIS_DRIVINGT_ACCELERATE_LINK
DIAXIS_DRIVINGT_STEER_LEFT_LINK
DIAXIS_DRIVINGT_STEER_RIGHT_LINK
DIAXIS_DRIVINGT_BARREL_UP_LINK
DIAXIS_DRIVINGT_BARREL_DOWN_LINK
DIAXIS_DRIVINGT_GLANCE_LEFT_LINK
DIAXIS_DRIVINGT_GLANCE_RIGHT_LINK
DIBUTTON_DRIVINGT_BRAKE
DIBUTTON_DRIVINGT_DASHBOARD
DIBUTTON_DRIVINGT_DEVICE
DIBUTTON_DRIVINGT_FIRESECONDARY
DIBUTTON_DRIVINGT_PAUSE
DIBUTTON_DRIVINGT_VIEW
DIHATSWITCH_DRIVINGT_GLANCE


フライト ジャンル

次のジャンルは、プレーヤーが航空機や宇宙船を制御するゲームおよびシミュレーションで使用される。

  • 空中戦
  • 民間機フライト
  • ヘリコプタ戦
  • 宇宙戦


空中戦

DIVIRTUAL_FLYING_MILITARY ジャンルには、固定翼機による空中戦闘シミュレーション用のコントロールが含まれる。

優先順位 1 のコントロール
DIAXIS_FLYINGM_BANK
DIAXIS_FLYINGM_PITCH
DIAXIS_FLYINGM_THROTTLE
DIBUTTON_FLYINGM_FIRE
DIBUTTON_FLYINGM_MENU
DIBUTTON_FLYINGM_TARGET
DIBUTTON_FLYINGM_WEAPONS

優先順位 2 のコントロール
DIAXIS_FLYINGM_BRAKE
DIAXIS_FLYINGM_FLAPS
DIAXIS_FLYINGM_RUDDER
DIBUTTON_FLYINGM_BRAKE_LINK
DIBUTTON_FLYINGM_COUNTER
DIBUTTON_FLYINGM_DEVICE
DIBUTTON_FLYINGM_DISPLAY
DIBUTTON_FLYINGM_FASTER_LINK
DIBUTTON_FLYINGM_FIRESECONDARY
DIBUTTON_FLYINGM_FLAPSDOWN
DIBUTTON_FLYINGM_FLAPSUP
DIBUTTON_FLYINGM_GEAR
DIBUTTON_FLYINGM_GLANCE_DOWN_LINK
DIBUTTON_FLYINGM_GLANCE_LEFT_LINK
DIBUTTON_FLYINGM_GLANCE_RIGHT_LINK
DIBUTTON_FLYINGM_GLANCE_UP_LINK
DIBUTTON_FLYINGM_PAUSE
DIBUTTON_FLYINGM_SLOWER_LINK
DIBUTTON_FLYINGM_VIEW
DIHATSWITCH_FLYINGM_GLANCE


民間機フライト

DIVIRTUAL_FLYING_CIVILIAN ジャンルには、非戦闘フライト シミュレーション用のコントロールが含まれる。

優先順位 1 のコントロール
DIAXIS_FLYINGC_BANK
DIAXIS_FLYINGC_PITCH
DIAXIS_FLYINGC_THROTTLE
DIBUTTON_FLYINGC_DISPLAY
DIBUTTON_FLYINGC_GEAR
DIBUTTON_FLYINGC_MENU
DIBUTTON_FLYINGC_VIEW

優先順位 2 のコントロール
DIAXIS_FLYINGC_BRAKE
DIAXIS_FLYINGC_FLAPS
DIAXIS_FLYINGC_RUDDER
DIBUTTON_FLYINGC_BRAKE_LINK
DIBUTTON_FLYINGC_DEVICE
DIBUTTON_FLYINGC_FASTER_LINK
DIBUTTON_FLYINGC_FLAPSDOWN
DIBUTTON_FLYINGC_FLAPSUP
DIBUTTON_FLYINGC_GLANCE_DOWN_LINK
DIBUTTON_FLYINGC_GLANCE_LEFT_LINK
DIBUTTON_FLYINGC_GLANCE_RIGHT_LINK
DIBUTTON_FLYINGC_GLANCE_UP_LINK
DIBUTTON_FLYINGC_PAUSE
DIBUTTON_FLYINGC_SLOWER_LINK
DIHATSWITCH_FLYINGC_GLANCE


ヘリコプタ戦

DIVIRTUAL_FLYING_HELICOPTER ジャンルには、ヘリコプタ戦闘シミュレーション用のコントロールが含まれる。

優先順位 1 のコントロール
DIAXIS_FLYINGH_BANK
DIAXIS_FLYINGH_COLLECTIVE
DIAXIS_FLYINGH_PITCH
DIBUTTON_FLYINGH_FIRE
DIBUTTON_FLYINGH_MENU
DIBUTTON_FLYINGH_TARGET
DIBUTTON_FLYINGH_WEAPONS

優先順位 2 のコントロール
DIAXIS_FLYINGH_THROTTLE
DIAXIS_FLYINGH_TORQUE
DIBUTTON_FLYINGH_COUNTER
DIBUTTON_FLYINGH_DEVICE
DIBUTTON_FLYINGH_FASTER_LINK
DIBUTTON_FLYINGH_FIRESECONDARY
DIBUTTON_FLYINGH_GEAR
DIBUTTON_FLYINGH_GLANCE_DOWN_LINK
DIBUTTON_FLYINGH_GLANCE_LEFT_LINK
DIBUTTON_FLYINGH_GLANCE_RIGHT_LINK
DIBUTTON_FLYINGH_GLANCE_UP_LINK
DIBUTTON_FLYINGH_PAUSE
DIBUTTON_FLYINGH_SLOWER_LINK
DIBUTTON_FLYINGH_VIEW
DIHATSWITCH_FLYINGH_GLANCE


宇宙戦

DIVIRTUAL_SPACESIM ジャンルには、宇宙船戦闘シミュレーション用のコントロールが含まれる。

優先順位 1 のコントロール
DIAXIS_SPACESIM_LATERAL
DIAXIS_SPACESIM_MOVE
DIAXIS_SPACESIM_THROTTLE
DIBUTTON_SPACESIM_FIRE
DIBUTTON_SPACESIM_MENU
DIBUTTON_SPACESIM_TARGET
DIBUTTON_SPACESIM_WEAPONS

優先順位 2 のコントロール
DIAXIS_SPACESIM_CLIMB
DIAXIS_SPACESIM_ROTATE
DIBUTTON_SPACESIM_BACKWARD_LINK
DIBUTTON_SPACESIM_DEVICE
DIBUTTON_SPACESIM_DISPLAY
DIBUTTON_SPACESIM_FASTER_LINK
DIBUTTON_SPACESIM_FIRESECONDARY
DIBUTTON_SPACESIM_FORWARD_LINK
DIBUTTON_SPACESIM_GEAR
DIBUTTON_SPACESIM_GLANCE_DOWN_LINK
DIBUTTON_SPACESIM_GLANCE_LEFT_LINK
DIBUTTON_SPACESIM_GLANCE_RIGHT_LINK
DIBUTTON_SPACESIM_GLANCE_UP_LINK
DIBUTTON_SPACESIM_LEFT_LINK
DIBUTTON_SPACESIM_LOWER
DIBUTTON_SPACESIM_PAUSE
DIBUTTON_SPACESIM_RAISE
DIBUTTON_SPACESIM_RIGHT_LINK
DIBUTTON_SPACESIM_SLOWER_LINK
DIBUTTON_SPACESIM_TURN_LEFT_LINK
DIBUTTON_SPACESIM_TURN_RIGHT_LINK
DIBUTTON_SPACESIM_VIEW
DIHATSWITCH_SPACESIM_GLANCE


スポーツ ジャンル

次のジャンルには、スポーツ ゲームやシミュレーション用のコントロールが含まれる。

  • 野球バッティング
  • 野球フィールディング
  • 野球ピッチング
  • バスケットボール ディフェンス
  • バスケットボール オフェンス
  • フィッシング
  • フットボール ディフェンス
  • フットボール オフェンス
  • フットボール プレー
  • フットボール クォーターバック
  • ゴルフ
  • ホッケー ディフェンス
  • ホッケー ゴールキーパー
  • ホッケー オフェンス
  • ハンティング
  • マウンテン バイク
  • ラケット
  • スキー
  • サッカー ディフェンス
  • サッカー オフェンス


野球バッティング

DIVIRTUAL_SPORTS_BASEBALL_BAT ジャンルには、野球の打者用のコントロールが含まれる。

優先順位 1 のコントロール
DIAXIS_BASEBALLB_LATERAL
DIAXIS_BASEBALLB_MOVE
DIBUTTON_BASEBALLB_BUNT
DIBUTTON_BASEBALLB_BURST
DIBUTTON_BASEBALLB_CONTACT
DIBUTTON_BASEBALLB_MENU
DIBUTTON_BASEBALLB_NORMAL
DIBUTTON_BASEBALLB_POWER
DIBUTTON_BASEBALLB_SELECT
DIBUTTON_BASEBALLB_SLIDE
DIBUTTON_BASEBALLB_STEAL

優先順位 2 のコントロール
DIBUTTON_BASEBALLB_BACK_LINK
DIBUTTON_BASEBALLB_BOX
DIBUTTON_BASEBALLB_DEVICE
DIBUTTON_BASEBALLB_FORWARD_LINK
DIBUTTON_BASEBALLB_LEFT_LINK
DIBUTTON_BASEBALLB_NOSTEAL
DIBUTTON_BASEBALLB_PAUSE
DIBUTTON_BASEBALLB_RIGHT_LINK


野球フィールディング

DIVIRTUAL_SPORTS_BASEBALL_FIELD ジャンルには、野球の野手用のコントロールが含まれる。

優先順位 1 のコントロール
DIAXIS_BASEBALLF_LATERAL
DIAXIS_BASEBALLF_MOVE
DIBUTTON_BASEBALLF_BURST
DIBUTTON_BASEBALLF_DIVE
DIBUTTON_BASEBALLF_JUMP
DIBUTTON_BASEBALLF_MENU
DIBUTTON_BASEBALLF_NEAREST
DIBUTTON_BASEBALLF_THROW1
DIBUTTON_BASEBALLF_THROW2

優先順位 2 のコントロール
DIBUTTON_BASEBALLF_AIM_LEFT_LINK
DIBUTTON_BASEBALLF_AIM_RIGHT_LINK
DIBUTTON_BASEBALLF_BACK_LINK
DIBUTTON_BASEBALLF_DEVICE
DIBUTTON_BASEBALLF_FORWARD_LINK
DIBUTTON_BASEBALLF_PAUSE
DIBUTTON_BASEBALLF_SHIFTIN
DIBUTTON_BASEBALLF_SHIFTOUT


野球ピッチング

DIVIRTUAL_SPORTS_BASEBALL_PITCH ジャンルには、野球の投手用のコントロールが含まれる。

優先順位 1 のコントロール
DIAXIS_BASEBALLP_LATERAL
DIAXIS_BASEBALLP_MOVE
DIBUTTON_BASEBALLP_BASE
DIBUTTON_BASEBALLP_FAKE
DIBUTTON_BASEBALLP_MENU
DIBUTTON_BASEBALLP_PITCH
DIBUTTON_BASEBALLP_SELECT
DIBUTTON_BASEBALLP_THROW

優先順位 2 のコントロール
DIBUTTON_BASEBALLP_BACK_LINK
DIBUTTON_BASEBALLP_DEVICE
DIBUTTON_BASEBALLP_FORWARD_LINK
DIBUTTON_BASEBALLP_LEFT_LINK
DIBUTTON_BASEBALLP_LOOK
DIBUTTON_BASEBALLP_PAUSE
DIBUTTON_BASEBALLP_RIGHT_LINK
DIBUTTON_BASEBALLP_WALK


バスケットボール ディフェンス

DIVIRTUAL_SPORTS_BASKETBALL_DEFENSE ジャンルには、バスケットボールの守備動作用のコントロールが含まれる。

優先順位 1 のコントロール
DIAXIS_BBALLD_LATERAL
DIAXIS_BBALLD_MOVE
DIBUTTON_BBALLD_BURST
DIBUTTON_BBALLD_FAKE
DIBUTTON_BBALLD_JUMP
DIBUTTON_BBALLD_MENU
DIBUTTON_BBALLD_PLAY
DIBUTTON_BBALLD_PLAYER
DIBUTTON_BBALLD_SPECIAL
DIBUTTON_BBALLD_STEAL

優先順位 2 のコントロール
DIBUTTON_BBALLD_BACK_LINK
DIBUTTON_BBALLD_DEVICE
DIBUTTON_BBALLD_FORWARD_LINK
DIBUTTON_BBALLD_LEFT_LINK
DIBUTTON_BBALLD_PAUSE
DIBUTTON_BBALLD_RIGHT_LINK
DIBUTTON_BBALLD_SUBSTITUTE
DIBUTTON_BBALLD_TIMEOUT
DIHATSWITCH_BBALLD_GLANCE


バスケットボール オフェンス

DIVIRTUAL_SPORTS_BASKETBALL_OFFENSE ジャンルには、バスケットボールの試合でボールを持つプレーヤー用のコントロールが含まれる。

優先順位 1 のコントロール
DIAXIS_BBALLO_LATERAL
DIAXIS_BBALLO_MOVE
DIBUTTON_BBALLO_BURST
DIBUTTON_BBALLO_CALL
DIBUTTON_BBALLO_DUNK
DIBUTTON_BBALLO_FAKE
DIBUTTON_BBALLO_MENU
DIBUTTON_BBALLO_PASS
DIBUTTON_BBALLO_PLAYER
DIBUTTON_BBALLO_SHOOT
DIBUTTON_BBALLO_SPECIAL

優先順位 2 のコントロール
DIBUTTON_BBALLO_BACK_LINK
DIBUTTON_BBALLO_DEVICE
DIBUTTON_BBALLO_FORWARD_LINK
DIBUTTON_BBALLO_JAB
DIBUTTON_BBALLO_LEFT_LINK
DIBUTTON_BBALLO_PAUSE
DIBUTTON_BBALLO_PLAY
DIBUTTON_BBALLO_POST
DIBUTTON_BBALLO_RIGHT_LINK
DIBUTTON_BBALLO_SCREEN
DIBUTTON_BBALLO_SUBSTITUTE
DIBUTTON_BBALLO_TIMEOUT
DIHATSWITCH_BBALLO_GLANCE


フィッシング

DIVIRTUAL_SPORTS_FISHING ジャンルには、スポーツ フィッシング シミュレーション用のコントロールが含まれる。

優先順位 1 のコントロール
DIAXIS_FISHING_LATERAL
DIAXIS_FISHING_MOVE
DIBUTTON_FISHING_BAIT
DIBUTTON_FISHING_BINOCULAR
DIBUTTON_FISHING_CAST
DIBUTTON_FISHING_MAP
DIBUTTON_FISHING_MENU
DIBUTTON_FISHING_TYPE

優先順位 2 のコントロール
DIAXIS_FISHING_ROTATE
DIBUTTON_FISHING_BACK_LINK
DIBUTTON_FISHING_CROUCH
DIBUTTON_FISHING_DEVICE
DIBUTTON_FISHING_DISPLAY
DIBUTTON_FISHING_FORWARD_LINK
DIBUTTON_FISHING_JUMP
DIBUTTON_FISHING_LEFT_LINK
DIBUTTON_FISHING_PAUSE
DIBUTTON_FISHING_RIGHT_LINK
DIBUTTON_FISHING_ROTATE_LEFT_LINK
DIBUTTON_FISHING_ROTATE_RIGHT_LINK
DIHATSWITCH_FISHING_GLANCE


フットボール ディフェンス

DIVIRTUAL_SPORTS_FOOTBALL_DEFENSE ジャンルには、アメリカン フットボールのディフェンス側のコントロールが含まれる。

優先順位 1 のコントロール
DIAXIS_FOOTBALLD_LATERAL
DIAXIS_FOOTBALLD_MOVE
DIBUTTON_FOOTBALLD_FAKE
DIBUTTON_FOOTBALLD_JUMP
DIBUTTON_FOOTBALLD_MENU
DIBUTTON_FOOTBALLD_PLAY
DIBUTTON_FOOTBALLD_SELECT
DIBUTTON_FOOTBALLD_SUPERTACKLE
DIBUTTON_FOOTBALLD_TACKLE

優先順位 2 のコントロール
DIBUTTON_FOOTBALLD_AUDIBLE
DIBUTTON_FOOTBALLD_BACK_LINK
DIBUTTON_FOOTBALLD_BULLRUSH
DIBUTTON_FOOTBALLD_DEVICE
DIBUTTON_FOOTBALLD_FORWARD_LINK
DIBUTTON_FOOTBALLD_LEFT_LINK
DIBUTTON_FOOTBALLD_PAUSE
DIBUTTON_FOOTBALLD_RIGHT_LINK
DIBUTTON_FOOTBALLD_RIP
DIBUTTON_FOOTBALLD_SPIN
DIBUTTON_FOOTBALLD_SUBSTITUTE
DIBUTTON_FOOTBALLD_SWIM
DIBUTTON_FOOTBALLD_ZOOM


フットボール オフェンス

DIVIRTUAL_SPORTS_FOOTBALL_OFFENSE ジャンルには、アメリカン フットボールのボールキャリア用のコントロールが含まれる。

優先順位 1 のコントロール
DIAXIS_FOOTBALLO_LATERAL
DIAXIS_FOOTBALLO_MOVE
DIBUTTON_FOOTBALLO_JUMP
DIBUTTON_FOOTBALLO_LEFTARM
DIBUTTON_FOOTBALLO_MENU
DIBUTTON_FOOTBALLO_RIGHTARM
DIBUTTON_FOOTBALLO_SPIN
DIBUTTON_FOOTBALLO_THROW

優先順位 2 のコントロール
DIBUTTON_FOOTBALLO_BACK_LINK
DIBUTTON_FOOTBALLO_DEVICE
DIBUTTON_FOOTBALLO_DIVE
DIBUTTON_FOOTBALLO_FORWARD_LINK
DIBUTTON_FOOTBALLO_JUKE
DIBUTTON_FOOTBALLO_LEFT_LINK
DIBUTTON_FOOTBALLO_PAUSE
DIBUTTON_FOOTBALLO_RIGHT_LINK
DIBUTTON_FOOTBALLO_SHOULDER
DIBUTTON_FOOTBALLO_SUBSTITUTE
DIBUTTON_FOOTBALLO_TURBO
DIBUTTON_FOOTBALLO_ZOOM


フットボール プレー

DIVIRTUAL_SPORTS_FOOTBALL_FIELD ジャンルには、アメリカン フットボール用の一般的なコントロールが含まれる。

優先順位 1 のコントロール
DIBUTTON_FOOTBALLP_HELP
DIBUTTON_FOOTBALLP_MENU
DIBUTTON_FOOTBALLP_PLAY
DIBUTTON_FOOTBALLP_SELECT

優先順位 2 のコントロール
DIBUTTON_FOOTBALLP_DEVICE
DIBUTTON_FOOTBALLP_PAUSE


フットボール クォーターバック

DIVIRTUAL_SPORTS_FOOTBALL_QBCK ジャンルには、アメリカン フットボールのクォーターバック用のコントロールが含まれる。

優先順位 1 のコントロール
DIAXIS_FOOTBALLQ_LATERAL
DIAXIS_FOOTBALLQ_MOVE
DIBUTTON_FOOTBALLQ_FAKE
DIBUTTON_FOOTBALLQ_JUMP
DIBUTTON_FOOTBALLQ_MENU
DIBUTTON_FOOTBALLQ_PASS
DIBUTTON_FOOTBALLQ_SELECT
DIBUTTON_FOOTBALLQ_SLIDE
DIBUTTON_FOOTBALLQ_SNAP

優先順位 2 のコントロール
DIBUTTON_FOOTBALLQ_AUDIBLE
DIBUTTON_FOOTBALLQ_BACK_LINK
DIBUTTON_FOOTBALLQ_DEVICE
DIBUTTON_FOOTBALLQ_FAKESNAP
DIBUTTON_FOOTBALLQ_FORWARD_LINK
DIBUTTON_FOOTBALLQ_LEFT_LINK
DIBUTTON_FOOTBALLQ_MOTION
DIBUTTON_FOOTBALLQ_PAUSE
DIBUTTON_FOOTBALLQ_RIGHT_LINK


ゴルフ

DIVIRTUAL_SPORTS_GOLF ジャンルには、ゴルフ用のコントロールが含まれる。

優先順位 1 のコントロール
DIAXIS_GOLF_LATERAL
DIAXIS_GOLF_MOVE
DIBUTTON_GOLF_DOWN
DIBUTTON_GOLF_FLYBY
DIBUTTON_GOLF_MENU
DIBUTTON_GOLF_SELECT
DIBUTTON_GOLF_SWING
DIBUTTON_GOLF_TERRAIN
DIBUTTON_GOLF_UP

優先順位 2 のコントロール
DIBUTTON_GOLF_BACK_LINK
DIBUTTON_GOLF_DEVICE
DIBUTTON_GOLF_FORWARD_LINK
DIBUTTON_GOLF_LEFT_LINK
DIBUTTON_GOLF_PAUSE
DIBUTTON_GOLF_RIGHT_LINK
DIBUTTON_GOLF_SUBSTITUTE
DIBUTTON_GOLF_TIMEOUT
DIBUTTON_GOLF_ZOOM
DIHATSWITCH_GOLF_SCROLL


ホッケー ディフェンス

DIVIRTUAL_SPORTS_HOCKEY_DEFENSE ジャンルには、ホッケーの守備動作用のコントロールが含まれる。

優先順位 1 のコントロール
DIAXIS_HOCKEYD_LATERAL
DIAXIS_HOCKEYD_MOVE
DIBUTTON_HOCKEYD_BLOCK
DIBUTTON_HOCKEYD_BURST
DIBUTTON_HOCKEYD_FAKE
DIBUTTON_HOCKEYD_MENU
DIBUTTON_HOCKEYD_PLAYER
DIBUTTON_HOCKEYD_STEAL

優先順位 2 のコントロール
DIBUTTON_HOCKEYD_BACK_LINK
DIBUTTON_HOCKEYD_DEVICE
DIBUTTON_HOCKEYD_FORWARD_LINK
DIBUTTON_HOCKEYD_LEFT_LINK
DIBUTTON_HOCKEYD_PAUSE
DIBUTTON_HOCKEYD_RIGHT_LINK
DIBUTTON_HOCKEYD_STRATEGY
DIBUTTON_HOCKEYD_SUBSTITUTE
DIBUTTON_HOCKEYD_TIMEOUT
DIBUTTON_HOCKEYD_ZOOM
DIHATSWITCH_HOCKEYD_SCROLL


ホッケー ゴールキーパー

DIVIRTUAL_SPORTS_HOCKEY_GOALIE ジャンルには、ホッケーのゴールキーパー用のコントロールが含まれる。

優先順位 1 のコントロール
DIAXIS_HOCKEYG_LATERAL
DIAXIS_HOCKEYG_MOVE
DIBUTTON_HOCKEYG_BLOCK
DIBUTTON_HOCKEYG_MENU
DIBUTTON_HOCKEYG_PASS
DIBUTTON_HOCKEYG_POKE
DIBUTTON_HOCKEYG_STEAL

優先順位 2 のコントロール
DIBUTTON_HOCKEYG_BACK_LINK
DIBUTTON_HOCKEYG_DEVICE
DIBUTTON_HOCKEYG_FORWARD_LINK
DIBUTTON_HOCKEYG_LEFT_LINK
DIBUTTON_HOCKEYG_PAUSE
DIBUTTON_HOCKEYG_RIGHT_LINK
DIBUTTON_HOCKEYG_STRATEGY
DIBUTTON_HOCKEYG_SUBSTITUTE
DIBUTTON_HOCKEYG_TIMEOUT
DIBUTTON_HOCKEYG_ZOOM
DIHATSWITCH_HOCKEYG_SCROLL


ホッケー オフェンス

DIVIRTUAL_SPORTS_HOCKEY_OFFENSE ジャンルには、ホッケーの攻撃動作用のコントロールが含まれる。

優先順位 1 のコントロール
DIAXIS_HOCKEYO_LATERAL
DIAXIS_HOCKEYO_MOVE
DIBUTTON_HOCKEYO_BURST
DIBUTTON_HOCKEYO_FAKE
DIBUTTON_HOCKEYO_MENU
DIBUTTON_HOCKEYO_PASS
DIBUTTON_HOCKEYO_SHOOT
DIBUTTON_HOCKEYO_SPECIAL

優先順位 2 のコントロール
DIBUTTON_HOCKEYO_BACK_LINK
DIBUTTON_HOCKEYO_DEVICE
DIBUTTON_HOCKEYO_FORWARD_LINK
DIBUTTON_HOCKEYO_LEFT_LINK
DIBUTTON_HOCKEYO_PAUSE
DIBUTTON_HOCKEYO_RIGHT_LINK
DIBUTTON_HOCKEYO_STRATEGY
DIBUTTON_HOCKEYO_SUBSTITUTE
DIBUTTON_HOCKEYO_TIMEOUT
DIBUTTON_HOCKEYO_ZOOM
DIHATSWITCH_HOCKEYO_SCROLL


ハンティング

DIVIRTUAL_SPORTS_HUNTING ジャンルには、ハンティング シミュレーション用のコントロールが含まれる。

優先順位 1 のコントロール
DIAXIS_HUNTING_LATERAL
DIAXIS_HUNTING_MOVE
DIBUTTON_HUNTING_AIM
DIBUTTON_HUNTING_BINOCULAR
DIBUTTON_HUNTING_CALL
DIBUTTON_HUNTING_FIRE
DIBUTTON_HUNTING_MAP
DIBUTTON_HUNTING_MENU
DIBUTTON_HUNTING_SPECIAL
DIBUTTON_HUNTING_WEAPON

優先順位 2 のコントロール
DIAXIS_HUNTING_ROTATE
DIBUTTON_HUNTING_BACK_LINK
DIBUTTON_HUNTING_CROUCH
DIBUTTON_HUNTING_DEVICE
DIBUTTON_HUNTING_DISPLAY
DIBUTTON_HUNTING_FIRESECONDARY
DIBUTTON_HUNTING_FORWARD_LINK
DIBUTTON_HUNTING_JUMP
DIBUTTON_HUNTING_LEFT_LINK
DIBUTTON_HUNTING_PAUSE
DIBUTTON_HUNTING_RIGHT_LINK
DIBUTTON_HUNTING_ROTATE_LEFT_LINK
DIBUTTON_HUNTING_ROTATE_RIGHT_LINK
DIHATSWITCH_HUNTING_GLANCE


マウンテン バイク

DIVIRTUAL_SPORTS_BIKING_MOUNTAIN には、マウンテン バイク用のコントロールが含まれる。

優先順位 1 のコントロール
DIAXIS_BIKINGM_PEDAL
DIAXIS_BIKINGM_TURN
DIBUTTON_BIKINGM_CAMERA
DIBUTTON_BIKINGM_JUMP
DIBUTTON_BIKINGM_MENU
DIBUTTON_BIKINGM_SELECT
DIBUTTON_BIKINGM_SPECIAL1
DIBUTTON_BIKINGM_SPECIAL2

優先順位 2 のコントロール
DIAXIS_BIKINGM_BRAKE
DIBUTTON_BIKINGM_BRAKE_BUTTON_LINK
DIBUTTON_BIKINGM_DEVICE
DIBUTTON_BIKINGM_FASTER_LINK
DIBUTTON_BIKINGM_LEFT_LINK
DIBUTTON_BIKINGM_PAUSE
DIBUTTON_BIKINGM_RIGHT_LINK
DIBUTTON_BIKINGM_SLOWER_LINK
DIBUTTON_BIKINGM_ZOOM
DIHATSWITCH_BIKINGM_SCROLL


ラケット

DIVIRTUAL_SPORTS_RACQUET ジャンルには、テニス、卓球、スカッシュなどのラケット ゲーム用のコントロールが含まれている。

優先順位 1 のコントロール
DIAXIS_RACQUET_LATERAL
DIAXIS_RACQUET_MOVE
DIBUTTON_RACQUET_BACKSWING
DIBUTTON_RACQUET_MENU
DIBUTTON_RACQUET_SELECT
DIBUTTON_RACQUET_SMASH
DIBUTTON_RACQUET_SPECIAL
DIBUTTON_RACQUET_SWING

優先順位 2 のコントロール
DIBUTTON_RACQUET_BACK_LINK
DIBUTTON_RACQUET_DEVICE
DIBUTTON_RACQUET_FORWARD_LINK
DIBUTTON_RACQUET_LEFT_LINK
DIBUTTON_RACQUET_PAUSE
DIBUTTON_RACQUET_RIGHT_LINK
DIBUTTON_RACQUET_SUBSTITUTE
DIBUTTON_RACQUET_TIMEOUT
DIHATSWITCH_RACQUET_GLANCE


スキー

DIVIRTUAL_SPORTS_SKIING ジャンルには、スキー用のコントロール、およびスノーボードやスケートボードなど類似スポーツのシミュレーション用コントロールが含まれる。

優先順位 1 のコントロール
DIAXIS_SKIING_SPEED
DIAXIS_SKIING_TURN
DIBUTTON_SKIING_CAMERA
DIBUTTON_SKIING_CROUCH
DIBUTTON_SKIING_JUMP
DIBUTTON_SKIING_MENU
DIBUTTON_SKIING_SELECT
DIBUTTON_SKIING_SPECIAL1
DIBUTTON_SKIING_SPECIAL2

優先順位 2 のコントロール
DIBUTTON_SKIING_DEVICE
DIBUTTON_SKIING_FASTER_LINK
DIBUTTON_SKIING_LEFT_LINK
DIBUTTON_SKIING_PAUSE
DIBUTTON_SKIING_RIGHT_LINK
DIBUTTON_SKIING_SLOWER_LINK
DIBUTTON_SKIING_ZOOM
DIHATSWITCH_SKIING_GLANCE


サッカー ディフェンス

DIVIRTUAL_SPORTS_SOCCER_DEFENSE ジャンルには、サッカーの守備動作用のコントロールが含まれる。

優先順位 1 のコントロール
DIAXIS_SOCCERD_LATERAL
DIAXIS_SOCCERD_MOVE
DIBUTTON_SOCCERD_BLOCK
DIBUTTON_SOCCERD_FAKE
DIBUTTON_SOCCERD_MENU
DIBUTTON_SOCCERD_PLAYER
DIBUTTON_SOCCERD_SELECT
DIBUTTON_SOCCERD_SLIDE
DIBUTTON_SOCCERD_SPECIAL
DIBUTTON_SOCCERD_STEAL

優先順位 2 のコントロール
DIBUTTON_SOCCERD_BACK_LINK
DIBUTTON_SOCCERD_CLEAR
DIBUTTON_SOCCERD_DEVICE
DIBUTTON_SOCCERD_FORWARD_LINK
DIBUTTON_SOCCERD_FOUL
DIBUTTON_SOCCERD_GOALIECHARGE
DIBUTTON_SOCCERD_HEAD
DIBUTTON_SOCCERD_LEFT_LINK
DIBUTTON_SOCCERD_PAUSE
DIBUTTON_SOCCERD_RIGHT_LINK
DIBUTTON_SOCCERD_SUBSTITUTE
DIHATSWITCH_SOCCERD_GLANCE


サッカー オフェンス

DIVIRTUAL_SPORTS_SOCCER_OFFENSE ジャンルには、サッカーの攻撃動作用のコントロールが含まれる。

優先順位 1 のコントロール
DIAXIS_SOCCERO_BEND
DIAXIS_SOCCERO_LATERAL
DIAXIS_SOCCERO_MOVE
DIBUTTON_SOCCERO_FAKE
DIBUTTON_SOCCERO_MENU
DIBUTTON_SOCCERO_PASS
DIBUTTON_SOCCERO_PLAYER
DIBUTTON_SOCCERO_SELECT
DIBUTTON_SOCCERO_SHOOT
DIBUTTON_SOCCERO_SPECIAL1

優先順位 2 のコントロール
DIBUTTON_SOCCERD_BACK_LINK
DIBUTTON_SOCCERD_FORWARD_LINK
DIBUTTON_SOCCERD_RIGHT_LINK
DIBUTTON_SOCCERO_CONTROL
DIBUTTON_SOCCERO_DEVICE
DIBUTTON_SOCCERO_HEAD
DIBUTTON_SOCCERO_LEFT_LINK
DIBUTTON_SOCCERO_PASSTHRU
DIBUTTON_SOCCERO_PAUSE
DIBUTTON_SOCCERO_SHOOTHIGH
DIBUTTON_SOCCERO_SHOOTLOW
DIBUTTON_SOCCERO_SPRINT
DIBUTTON_SOCCERO_SUBSTITUTE
DIHATSWITCH_SOCCERO_GLANCE


ストラテジ ジャンル

次のジャンルには、ストラテジ、ロールプレイング、およびアドベンチャ ゲーム用のコントロールが含まれる。

  • ロールプレイング
  • ターンベース


ロールプレイング

DIVIRTUAL_STRATEGY_ROLEPLAYING ジャンルには、移動、問題解決、および武器や魔法による戦闘を主な活動とするロールプレイング ゲームやアドベンチャ ゲーム用のコントロールが含まれる。

優先順位 1 のコントロール
DIAXIS_STRATEGYR_LATERAL
DIAXIS_STRATEGYR_MOVE
DIBUTTON_STRATEGYR_APPLY
DIBUTTON_STRATEGYR_ATTACK
DIBUTTON_STRATEGYR_CAST
DIBUTTON_STRATEGYR_CROUCH
DIBUTTON_STRATEGYR_GET
DIBUTTON_STRATEGYR_JUMP
DIBUTTON_STRATEGYR_MENU
DIBUTTON_STRATEGYR_SELECT

優先順位 2 のコントロール
DIAXIS_STRATEGYR_ROTATE
DIBUTTON_STRATEGYR_BACK_LINK
DIBUTTON_STRATEGYR_DEVICE
DIBUTTON_STRATEGYR_DISPLAY
DIBUTTON_STRATEGYR_FORWARD_LINK
DIBUTTON_STRATEGYR_LEFT_LINK
DIBUTTON_STRATEGYR_MAP
DIBUTTON_STRATEGYR_PAUSE
DIBUTTON_STRATEGYR_RIGHT_LINK
DIBUTTON_STRATEGYR_ROTATE_LEFT_LINK
DIBUTTON_STRATEGYR_ROTATE_RIGHT_LINK
DIHATSWITCH_STRATEGYR_GLANCE


ターンベース

DIVIRTUAL_STRATEGY_TURN ジャンルには、ターンベースのストラテジ ゲーム用のコントロールが含まれる。

優先順位 1 のコントロール
DIAXIS_STRATEGYT_LATERAL
DIAXIS_STRATEGYT_MOVE
DIBUTTON_STRATEGYT_APPLY
DIBUTTON_STRATEGYT_INSTRUCT
DIBUTTON_STRATEGYT_MENU
DIBUTTON_STRATEGYT_SELECT
DIBUTTON_STRATEGYT_TEAM
DIBUTTON_STRATEGYT_TURN

優先順位 2 のコントロール
DIBUTTON_STRATEGYT_BACK_LIN
DIBUTTON_STRATEGYT_DEVICE
DIBUTTON_STRATEGYT_DISPLAY
DIBUTTON_STRATEGYT_FORWARD_LINK
DIBUTTON_STRATEGYT_LEFT_LINK
DIBUTTON_STRATEGYT_MAP
DIBUTTON_STRATEGYT_PAUSE
DIBUTTON_STRATEGYT_RIGHT_LINK
DIBUTTON_STRATEGYT_ZOOM


キーボード マッピング定数

次の定数は、DIACTION 型の ActionName メンバで使用され、アクションを物理キーにマップする。

定数 | メモ
DIKEYBOARD_0 | メイン キーボード上
DIKEYBOARD_1 | メイン キーボード上
DIKEYBOARD_2 | メイン キーボード上
DIKEYBOARD_3 | メイン キーボード上
DIKEYBOARD_4 | メイン キーボード上
DIKEYBOARD_5 | メイン キーボード上
DIKEYBOARD_6 | メイン キーボード上
DIKEYBOARD_7 | メイン キーボード上
DIKEYBOARD_8 | メイン キーボード上
DIKEYBOARD_9 | メイン キーボード上
DIKEYBOARD_A |
DIKEYBOARD_ABNT_C1 | ブラジル語キーボードのテンキー上
DIKEYBOARD_ABNT_C2 | ブラジル語キーボードのテンキー上
DIKEYBOARD_ADD | テンキー上のプラス記号
DIKEYBOARD_APOSTROPHE |
DIKEYBOARD_APPS | アプリケーション キー
DIKEYBOARD_AT | 日本語キーボード上
DIKEYBOARD_AX | 日本語キーボード上
DIKEYBOARD_B |
DIKEYBOARD_BACK | BaackSpace キー
DIKEYBOARD_BACKSLASH |
DIKEYBOARD_C |
DIKEYBOARD_CALCULATOR |
DIKEYBOARD_CAPITAL | CapsLock
DIKEYBOARD_COLON | 日本語キーボード上
DIKEYBOARD_COMMA |
DIKEYBOARD_CONVERT | 日本語キーボード上
DIKEYBOARD_D |
DIKEYBOARD_DECIMAL | テンキー上のピリオド (小数点)
DIKEYBOARD_DELETE |
DIKEYBOARD_DIVIDE | テンキー上のスラッシュ (/)
DIKEYBOARD_DOWN | 下矢印キー
DIKEYBOARD_E |
DIKEYBOARD_END |
DIKEYBOARD_EQUALS | メイン キーボード上
DIKEYBOARD_ESCAPE |
DIKEYBOARD_F |
DIKEYBOARD_F1 |
DIKEYBOARD_F2 |
DIKEYBOARD_F3 |
DIKEYBOARD_F4 |
DIKEYBOARD_F5 |
DIKEYBOARD_F6 |
DIKEYBOARD_F7 |
DIKEYBOARD_F8 |
DIKEYBOARD_F9 |
DIKEYBOARD_F10 |
DIKEYBOARD_F11 |
DIKEYBOARD_F12 |
DIKEYBOARD_F13 | NEC PC-98 日本語キーボード上
DIKEYBOARD_F14 | NEC PC-98 日本語キーボード上
DIKEYBOARD_F15 | NEC PC-98 日本語キーボード上
DIKEYBOARD_G |
DIKEYBOARD_GRAVE | アクサン グラーブ (`) キー
DIKEYBOARD_H |
DIKEYBOARD_HOME |
DIKEYBOARD_I |
DIKEYBOARD_INSERT |
DIKEYBOARD_J |
DIKEYBOARD_K |
DIKEYBOARD_KANA | 日本語キーボード上
DIKEYBOARD_KANJI | 日本語キーボード上
DIKEYBOARD_L |
DIKEYBOARD_LBRACKET | 左角かっこ [
DIKEYBOARD_LCONTROL | 左 Ctrl キー
DIKEYBOARD_LEFT | 左矢印キー
DIKEYBOARD_LMENU | 左 Alt キー
DIKEYBOARD_LSHIFT | 左 Shift キー
DIKEYBOARD_LWIN | 左 Microsoft® Windows® キー
DIKEYBOARD_M |
DIKEYBOARD_MAIL |
DIKEYBOARD_MEDIASELECT |
DIKEYBOARD_MEDIASTOP |
DIKEYBOARD_MINUS | メイン キーボード上
DIKEYBOARD_MULTIPLY | テンキー上のアスタリスク キー (*)
DIKEYBOARD_MUTE |
DIKEYBOARD_MYCOMPUTER |
DIKEYBOARD_N |
DIKEYBOARD_NEXT | PageDown キー
DIKEYBOARD_NEXTTRACK | 次のトラック
DIKEYBOARD_NOCONVERT | 日本語キーボード上
DIKEYBOARD_NUMLOCK |
DIKEYBOARD_NUMPAD0 |
DIKEYBOARD_NUMPAD1 |
DIKEYBOARD_NUMPAD2 |
DIKEYBOARD_NUMPAD3 |
DIKEYBOARD_NUMPAD4 |
DIKEYBOARD_NUMPAD5 |
DIKEYBOARD_NUMPAD6 |
DIKEYBOARD_NUMPAD7 |
DIKEYBOARD_NUMPAD8 |
DIKEYBOARD_NUMPAD9 |
DIKEYBOARD_NUMPADCOMMA | NEC PC-98 日本語キーボードのテンキー上
DIKEYBOARD_NUMPADENTER |
DIKEYBOARD_NUMPADEQUALS | NEC PC-98 日本語キーボードのテンキー上
DIKEYBOARD_O |
DIKEYBOARD_OEM_102 | 英語キーボードおよびドイツ語キーボード上
DIKEYBOARD_P |
DIKEYBOARD_PAUSE |
DIKEYBOARD_PERIOD | メイン キーボード上
DIKEYBOARD_PLAYPAUSE |
DIKEYBOARD_POWER |
DIKEYBOARD_PREVTRACK | 前のトラック、日本語キーボードのサーカムフレックス
DIKEYBOARD_PRIOR | PageUp キー
DIKEYBOARD_Q |
DIKEYBOARD_R |
DIKEYBOARD_RBRACKET | 右角かっこ
DIKEYBOARD_RCONTROL | 右 Ctrl キー
DIKEYBOARD_RETURN | メイン キーボード上の Enter キー
DIKEYBOARD_RIGHT | 右矢印キー
DIKEYBOARD_RMENU | 右 Alt キー
DIKEYBOARD_RSHIFT | 右 Shift キー
DIKEYBOARD_RWIN | 右 Windows キー
DIKEYBOARD_S |
DIKEYBOARD_SCROLL | ScrollLock
DIKEYBOARD_SEMICOLON |
DIKEYBOARD_SLASH | メイン キーボード上のスラッシュ (/)
DIKEYBOARD_SLEEP |
DIKEYBOARD_SPACE | Space キー
DIKEYBOARD_STOP | NEC PC-98 日本語キーボード上
DIKEYBOARD_SUBTRACT | テンキー上のマイナス記号 (-)
DIKEYBOARD_SYSRQ |
DIKEYBOARD_T |
DIKEYBOARD_TAB |
DIKEYBOARD_U |
DIKEYBOARD_UNDERLINE | NEC PC-98 日本語キーボード上
DIKEYBOARD_UNLABELED | 日本語キーボード上
DIKEYBOARD_UP | 上矢印キー
DIKEYBOARD_V |
DIKEYBOARD_VOLUMEDOWN |
DIKEYBOARD_VOLUMEUP |
DIKEYBOARD_W |
DIKEYBOARD_WAKE |
DIKEYBOARD_WEBBACK |
DIKEYBOARD_WEBFAVORITES |
DIKEYBOARD_WEBFORWARD |
DIKEYBOARD_WEBHOME |
DIKEYBOARD_WEBREFRESH |
DIKEYBOARD_WEBSEARCH |
DIKEYBOARD_WEBSTOP |
DIKEYBOARD_X |
DIKEYBOARD_Y |
DIKEYBOARD_YEN | 日本語キーボード上
DIKEYBOARD_Z |


マウス マッピング定数

次の定数は、DIACTION 型の ActionName メンバで使用され、アクションをマウスの物理軸やボタンにマップする。

DIMOUSE_BUTTON0
DIMOUSE_BUTTON1
DIMOUSE_BUTTON2
DIMOUSE_BUTTON3
DIMOUSE_BUTTON4
DIMOUSE_BUTTON5
DIMOUSE_BUTTON6
DIMOUSE_BUTTON7
DIMOUSE_WHEEL
DIMOUSE_XAXIS
DIMOUSE_YAXIS
DIMOUSE_XAXISAB
DIMOUSE_YAXISAB

メモ : DIMOUSE_XAXISAB および DIMOUSE_YAXISAB は、マウスの x 軸と y 軸を表し、相対軸データではなく絶対軸データを返す。


DirectPlay 音声マッピング定数

次の定数は、DIACTION 型の ActionName メンバで使用され、アクションを Microsoft® DirectPlay® の音声デバイスのチャネルにマップする。

DIVOICE_CHANNEL1
DIVOICE_CHANNEL2
DIVOICE_CHANNEL3
DIVOICE_CHANNEL4
DIVOICE_CHANNEL5
DIVOICE_CHANNEL6
DIVOICE_CHANNEL7
DIVOICE_CHANNEL8
DIVOICE_ALL
DIVOICE_TEAM
DIVOICE_PLAYBACKMUTE
DIVOICE_RECORDMUTE
DIVOICE_TRANSMIT
DIVOICE_VOICECOMMAND


任意コントロール定数

次の定数は、DIACTION 型の ActionName メンバで使用され、アクションをデバイス上の一致するコントロールにマップする。

定数 | デバイス オブジェクト
DIAXIS_ANY_1 | 任意の軸。
DIAXIS_ANY_2 | 任意の軸。
DIAXIS_ANY_3 | 任意の軸。
DIAXIS_ANY_4 | 任意の軸。
DIAXIS_ANY_A_1 | 任意のアクセラレータ。
DIAXIS_ANY_A_2 | 任意のアクセラレータ。
DIAXIS_ANY_B_1 | 任意のブレーキ。
DIAXIS_ANY_B_2 | 任意のブレーキ。
DIAXIS_ANY_C_1 | 任意のクラッチ。
DIAXIS_ANY_C_2 | 任意のクラッチ。
DIAXIS_ANY_R_1 | 任意の r 軸。
DIAXIS_ANY_R_2 | 任意の r 軸。
DIAXIS_ANY_S_1 | 任意の s 軸。
DIAXIS_ANY_S_2 | 任意の s 軸。
DIAXIS_ANY_U_1 | 任意の u 軸。
DIAXIS_ANY_U_2 | 任意の u 軸。
DIAXIS_ANY_V_1 | 任意の v 軸。
DIAXIS_ANY_V_2 | 任意の v 軸。
DIAXIS_ANY_X_1 | 任意の x 軸。
DIAXIS_ANY_X_2 | 任意の x 軸。
DIAXIS_ANY_Y_1 | 任意の y 軸。
DIAXIS_ANY_Y_2 | 任意の y 軸。
DIAXIS_ANY_Z_1 | 任意の z 軸。
DIAXIS_ANY_Z_2 | 任意の z 軸。
DIBUTTON_ANY | 任意のボタン。
DIPOV_ANY_1 | 任意の視点コントローラ。
DIPOV_ANY_2 | 任意の視点コントローラ。
DIPOV_ANY_3 | 任意の視点コントローラ。
DIPOV_ANY_4 | 任意の視点コントローラ。

これらの定数を使って、ジャンルに定義されていない仮想コントロールにアプリケーション アクションをマップできる。このようなアクションは、ジャンル固有アクションの後にマップされる。マッパーが一致するコントロールをすべてジャンル固有アクションに既にマップしていた場合、すべてのアクションはマップされないまま残される。

任意コントロール アクションに優先度の差はない。デバイスに 1 つの x 軸があり、アクション配列が DIAXIS_ANY_1 および DIAXIS_ANY_X_1 を指定する場合、x 軸には、アクション配列の先頭に表示されるアクションがマップされる。


エラー コード

以下は、DirectInput メソッドと関数によって返されるエラー コードの一覧である。エラーは負の値によって示され、結合することができない。

それぞれのメソッドまたは関数はエラー値を返すことができるが、詳しくはそれぞれの説明を参照すること。本文中のエラー コードの一覧は、必然的に不完全になっている。たとえば、どんな DirectInput メソッドも DIERR_OUTOFMEMORY を返すことができるが、本文中では、このエラー コードはそのメソッドの戻り値としては明示されていない。

DI_OK
操作は、完全に終了した。この値は、標準の COM 戻り値である S_OK に等しい。
DIERR_ACQUIRED
操作は、デバイスが取得状態の間は実行できない。
DIERR_ALREADYINITIALIZED
このオブジェクトは初期化済みである。
DIERR_BADDRIVERVER
オブジェクトは、互換性のないドライバ バージョン、あるいは不適格または不完全なドライバ コンポーネントであるために作成できなかった。
DIERR_BETADIRECTINPUTVERSION
アプリケーションは、DirectInput のサポートされていないリリース前のバージョン用に作成されたものである。
DIERR_DEVICEFULL
デバイスはフルである。
DIERR_DEVICENOTREG
デバイスまたはデバイス インスタンスが DirectInput に登録されていない。この値は、標準の COM 戻り値である REGDB_E_CLASSNOTREG に等しい。
DIERR_EFFECTPLAYING
パラメータは、メモリ内では更新されたが、デバイスにはダウンロードされなかった。デバイスが再生中のエフェクトの更新をサポートしていないためである。
DIERR_GENERIC
DirectInput サブシステムで 原因不明のエラーが発生した。この値は、標準の COM 戻り値である E_FAIL に等しい。
DIERR_HANDLEEXISTS
デバイスは、既に、自身にイベント通知の関連付けをしている。この値は、標準の COM 戻り値である E_ACCESSDENIED に等しい。
DIERR_HASEFFECTS
エフェクトがデバイスにアタッチされているため、デバイスを再初期化できない。
DIERR_INCOMPLETEEFFECT
必須情報がないので、エフェクトをダウンロードできなかった。たとえば、エフェクトに関連する軸がなかったり、タイプ固有情報が与えられていない場合。
DIERR_INPUTLOST
入力デバイスのアクセス権を失った。再取得しなければならない。
DIERR_INVALIDHANDLE
無効なウィンドウ ハンドルがメソッドに渡された。
DIERR_INVALIDPARAM
無効なパラメータが戻ってくる関数に渡されたか、オブジェクトがその関数を呼び出せる状態になかった。この値は、標準の COM 戻り値である E_INVALIDARG に等しい。
DIERR_MAPFILEFAIL
ベンダーが提供するデバイスのアクション マッピング ファイルの読み込み中か、あるいはデバイスのユーザー構成ファイルの読み込みまたは書き込み中にエラーが発生したことを示す。
DIERR_MOREDATA
要求情報の一部がバッファに収まらなかった。
DIERR_NOAGGREGATION
オブジェクトは、集合化をサポートしない。
DIERR_NOINTERFACE
オブジェクトは、指定のインターフェイスをサポートしていない。この値は、標準の COM 戻り値である E_NOINTERFACE に等しい。
DIERR_NOTACQUIRED
操作は、デバイスが取得されない限り実行できない。
DIERR_NOTBUFFERED
デバイスは、バッファリングされていない。バッファリングを有効にするには DIPROP_BUFFERSIZE プロパティを設定する。
DIERR_NOTDOWNLOADED
エフェクトがダウンロードされていない。
DIERR_NOTEXCLUSIVEACQUIRED
操作は、デバイスが DISCL_EXCLUSIVE モードで取得されていなければ実行できない。
DIERR_NOTFOUND
要求されたオブジェクトは存在しない。
DIERR_NOTINITIALIZED
このオブジェクトは、初期化されていなかった。
DIERR_OBJECTNOTFOUND
要求されたオブジェクトは存在しない。
DIERR_OLDDIRECTINPUTVERSION
アプリケーションは、より新しいバージョンの DirectInput を必要とする。
DIERR_OTHERAPPHASPRIO
ほかのアプリケーションの優先レベルの方が高いので、この呼び出しの実行がうまくいかない。この値は、標準の COM 戻り値である E_ACCESSDENIED に等しい。このエラーは、アプリケーションのデバイスに対するアクセス権が、フォアグラウンド アクセス権であるにもかかわらず、バックグラウンドにいるときに、デバイスを取得しようとした場合に返される。
DIERR_OUTOFMEMORY
DirectInput サブシステムが呼び出しを完了するのに十分なメモリを割り当てることができなかった。この値は、標準の COM 戻り値である E_OUTOFMEMORY に等しい。
DIERR_READONLY
指定のプロパティは変更できない。この値は、標準の COM 戻り値である E_ACCESSDENIED に等しい。
DIERR_REPORTFULL
送られる情報の方が、デバイスに送ることができる情報よりも多い。
DIERR_UNPLUGGED
この操作は、デバイスが接続されていない可能性を示す。
DIERR_UNSUPPORTED
この関数呼び出しは、この時点ではサポートされない。この値は、標準の COM 戻り値である E_NOTIMPL に等しい。
E_PENDING
データは、まだ使用不可である。


DirectPlay

Microsoft® DirectPlay® アプリケーション プログラミング インターフェイス (API) は、Microsoft DirectX® のコンポーネントであり、マルチプレーヤー ゲームなどのネットワーク アプリケーションの記述を可能にする。

DirectPlay は、DirectX のほかのコンポーネントと同じように、C、C++、および Microsoft Visual Basic® で使用できる。

DirectPlay ヘルプ全体の構成については、「ロードマップ」を参照すること。


ロードマップ

Microsoft® DirectPlay® に関する情報は、次のように構成されている。

DirectPlay の新機能。Microsoft DirectX® 8 でのこのコンポーネントの新しい機能。以前 DirectPlay を使用したことがある場合は、この項目を最初に読むこと。この技術は DirectX 7 以降に完全に再設計された。

DirectPlay の概要。DirectPlay とは何か、アプリケーションにとってどのように役立つかについて概要を示し、主要なオブジェクトとネットワーク アプリケーションを作成するために必要な手順を簡単に説明する。

DirectPlay について。基になるメカニズムを詳細に解説する。DirectPlay セッションの実装方法については説明しないが、実装の詳細を扱う時点でアプリケーション プログラミング インターフェイス (API) を理解するのに役立つ。

DirectPlay の使い方。API の使用に関する手引き。この項目にある目次で全体を把握し、具体的な情報が必要になったときに各部分を参照できる。リファレンス情報と共に使用すること。

DirectPlay Visual Basic サンプル。SDK の Visual Basic サンプル アプリケーションのガイド。

DirectPlay Visual Basic リファレンス。DirectPlay Visual Basic API の詳細情報。


DirectPlay の新機能

Microsoft® DirectX® のネットワーク コンポーネントは大きく変更された。Microsoft DirectPlay® には、新しいインターフェイス セットが導入され、ハードウェアへの直接アクセスがこれまで以上に可能になり、パフォーマンスが向上した。

DirectPlay の主な新機能を次に示す。

オブジェクトがが完全に書き換えられた。
ピアツーピア セッションとクライアント/サーバー セッションの作成に使用するオブジェクトを分離することにより、複雑なネットワーク アプリケーションの作成が容易になった。DirectPlay トランスポート セッション作成のためのオブジェクトには以下の機能がある。
DirectPlay8Peer
ピアツーピア セッションを作成するメソッドを提供する。
DirectPlay8Client
クライアント/サーバー アプリケーションのクライアント部分を作成するメソッドを提供する。
DirectPlay8Server
クライアント/サーバー アプリケーションのサーバー部分を作成するメソッドを提供する。
ロビーが DirectPlay の残りの部分から切り離された。
ロビー クライアントは DirectPlay アプリケーションと共に実行する必要がなくなった。ロビー サービス プロバイダまたはアプリケーションは、相手を考慮することなく、DirectPlay を実装できるようになった。ロビー実装が 2 つの単純化されたオブジェクトに分離された。
DirectPlay8LobbyClient
このオブジェクトは、ロビー クライアントの管理、およびロビー対応アプリケーションの列挙と起動に使用する。
DirectPlay8LobbiedApplication
このオブジェクトを使用し、ロビー起動可能なアプリケーションをシステムに登録し、アプリケーションをロビー起動できるようにする。また、このインターフェイスを使用すると、ロビーから接続情報を取得し、ユーザーに問い合わせずにゲームを起動することもできる。
音声転送が追加された。
DirectPlay Voice は、アプリケーションにリアルタイムの音声通信を追加する一連のオブジェクトを提供する。以下のオブジェクトが Dvoice.h ヘッダー ファイルに定義されている。
DirectPlayVoiceClient
DirectPlay Voice セッションでクライアントを作成し、管理するメソッドを提供する。
DirectPlayVoiceServer
DirectPlay Voice セッションをホストし、管理するメソッドを提供する。
DirectPlayVoiceTest
DirectPlay Voice のオーディオ構成のテストに使用する。
アドレス情報が GUID ベースのデータから URL ベースのデータ形式に移行された。
DirectPlay の以前のバージョンでは、実装しにくく、人間には読み取り不可能な GUID アドレスを使ったバイナリ データを使用していた。DirectX 8.0 の DirectPlay では、URL 形式のアドレス表記が導入された。DirectPlay は、新しいアドレッシング形式の作成および操作に使用するオブジェクトを提供する。
DirectPlay8Address
DirectPlay アドレスの作成と操作に使用する汎用アドレッシング メソッドを提供する。
さらに高い拡張性と改善されたメモリ管理が追加された。
利用者側の帯域幅の増加は、ネットワーク ゲームの設計と実装に大きな影響を与えた。DirectPlay では、スレッド プール管理が向上したため、開発者はスケーラブルでより堅牢であり、多数のマルチプレーヤー オンライン アプリケーションをサポートできるアプリケーションを簡単に作成できるようになった。
ファイアウォールのサポートが強化され、ネットワーク アドレス トランスレータが追加された。
ネットワーク アドレス トランスレータ (NAT)、ファイアウォール、およびそのほかのインターネット接続共有 (ICS) 方法を通過するネットワーク ゲームの作成は困難なことがある。特に、非保証 (UDP) トラフィックの場合、困難である。DirectPlay 8.0 ではこのような問題が考慮されているため、可能な限り NAT ソリューションがサポートされている。DirectPlay 8 の TCP/IP サービス プロバイダでは、ゲーム データ用として単一の UDP ポートを使用し、開発者はそのポートを選択できる。したがって、ファイアウォールや NAT を適切に構成できる。また、DirectPlay は UDP を利用し、クライアント/サーバー ゲームにおいて、一部の NAT が対象とするクライアントが構成を追加せずにゲームに接続できるようにする。


DirectPlay の概要

Microsoft® DirectPlay® API は、ゲームやチャット クライアントなどマルチプレーヤー アプリケーションを開発するためのツールを開発者に提供する。わかりやすくするため、このマニュアルでは、このようなアプリケーションをすべて「ゲーム」と呼ぶ。マルチプレーヤー アプリケーションには、2 つの基本的特徴がある。

  • 各自のコンピュータ上にゲーム クライアントを持つ複数の個人ユーザーがいる。
  • ユーザーのコンピュータを相互接続するための (おそらく中央サーバー経由の) ネットワーク リンクがある。

DirectPlay は、基本となるネットワークからアプリケーションを大きく隔離するレイヤを提供する。大部分の用途では、アプリケーションは単に DirectPlay API を使用し、DirectPlay がネットワーク通信の詳細を処理できるようにする。DirectPlay は、マルチプレーヤー アプリケーションのさまざまな面の実装プロセスを容易にするため、以下のような多くの機能を提供する。

  • ピアツーピア セッションとクライアント/サーバー セッションの両方を作成し管理する。
  • セッション内のユーザーとグループを管理する。
  • ネットワーク リンクやネットワーク条件が異なるセッション メンバ間でのメッセージングを管理する。
  • アプリケーションとロビーとの対話を可能にする。
  • ユーザー相互の音声通信を可能にする。

このドキュメントは、DirectPlay の能力の高度な概要を解説する。以下のトピックでは、マルチプレーヤー ゲームでの DirectPlay の使用方法の詳細を説明する。

  • セッションの作成と管理
  • DirectPlay ネットワーク通信
  • DirectPlay オブジェクトとの通信
  • DirectPlay ロビー サポート
  • DirectPlay 音声通信


セッションの作成と管理

ゲームのセッションとは、特定のマルチプレーヤー ゲームの 1 つのインスタンスである。1 つのセッションには同時にプレイする複数のユーザーがあり、それぞれが自分のコンピュータ上にゲーム クライアントを持っている。プレーヤーとは、ゲームの中のエンティティであり、各ゲームによって定義される。各ユーザーが、1 つのゲームに 1 人以上のプレーヤーを持つ場合もある。ただし、ゲーム アプリケーションは、個別の Microsoft® DirectPlay® インターフェイスまたは各プレーヤーのオブジェクトを使用して、これらのプレーヤーをアプリケーション自身で管理しなければならない。

セッション作成の最初の手順は、ユーザー グループの収集である。2 つの基本的方法がある。

  • 多くのゲーム セッションは、リモート コンピュータで実行されているロビー アプリケーションによってアレンジされている。この方法は、多くのインターネット ベースのゲームで使用されている。
  • また、各ユーザーのコンピュータを相互に通信させてゲームをアレンジすることもできる。この方法は、一般的に、参加するユーザー グループがすべて同じ LAN 上に存在するような場合に限定される。

セッションがアレンジされると、ゲームが起動し、ゲームプレーが開始される。セッションが進むにつれて、プレーヤーがセッションから消えたり、新しいプレーヤーが追加されたりする。詳細は個々のゲームによって異なる。

マルチプレーヤー ゲームでは、各ユーザーの UI は、セッション内のほかのすべてのユーザーの UI と同期することができる。したがって、マルチプレーヤー セッションの管理には、ユーザー間での継続的なメッセージのストリームが必要となる。たとえば、プレーヤーが移動するたびにメッセージが送信され、セッション内のほかのすべてのゲーム クライアント上でのそのプレーヤーの位置が更新される。DirectPlay の重要部分は、セッション内のすべてのコンピュータ間での効率的かつ柔軟なメッセージ送信をサポートする API 部分である。

セッションでのメッセージ送信のトポロジ構築には、主に 2 つの方法がある。ピアツーピアとクライアント/サーバーである。どちらのトポロジにも利点と制約があるため、どちらが自分のゲームに適しているかを評価する必要がある。

ここでは説明するトピックは、次のとおりである。

  • ピアツーピア トポロジ
  • クライアント/サーバー トポロジ


ピアツーピア トポロジ

ピアツーピアのゲームは、ネットワーク リンクで接続された各プレーヤーのコンピュータによって構成される。4 人のプレーヤーによるピアツーピア ゲームのトポロジを図解すると、次のようになる。

ゲームプレイは、各ユーザーのゲーム クライアントをほかのユーザーのクライアントと直接通信させることによって処理される。たとえば、あるユーザーが移動したとき、ゲーム クライアントは、ほかのユーザーのコンピュータ 1 台に対して 1 つずつ、合計 3 つの更新メッセージを送信しなければならない。

ピアツーピア ゲームは、ユーザーのコンピュータ上に常駐するロビー クライアント アプリケーションによってアレンジされ、起動するのが普通である。ロビー クライアントがセッションをアレンジする場合、以下のような 2 つの基本的な方法がある。

  • ロビー クライアントがほかの潜在的ユーザーのロビー クライアントと直接通信する。この方法は、たとえば同じ LAN サブネット上のユーザーにゲームをアレンジする場合に使用できる。
  • ロビー クライアントが、リモート コンピュータ上で実行されているロビー サーバー アプリケーションへのリンクとして機能する。インターネット ベースのゲームは普通はこの方法でアレンジされている。

セッションがアレンジされ起動すると、メッセージ送信の大部分またはすべてがユーザー間のメッセージになる。ロビー サーバーが関与している場合、このサーバーは、プレーヤーがゲームから離れたときにセッション メンバのリストを更新したり、新しいユーザーがセッションへの参加を要求できるようにするだけである。処理が必要ない場合は、サーバーはバックグラウンドにとどまり、一般的には送信されているメッセージもほとんど認識することはない。

サーバーは、存在しないか、少なくともゲーム プレイには直接かかわっていないため、1 人のユーザーがゲームのホストに指定される。ホストは、進行中のセッションへの新しいプレーヤーの参加など、論理的な詳細を処理する。

ピアツーピア ゲームの利点は、その単純さである。必要なものは、ゲーム クライアントを備えたプレーヤーの集団と、セッションを整理する方法のみである。ピアツーピア トポロジの最大の弱点は、スケーラビリティにある。ユーザー数が増加すると、それに比例してゲーム プレイを処理するために必要なメッセージ数も増加する。参加できるユーザーの最大数は、ゲームやネットワークの帯域幅にもよるが、一般的には 20 ～ 30 人以内である。


クライアント/サーバー トポロジ

クライアント/サーバー ゲームは、中央のサーバー コンピュータに接続された各プレーヤーのコンピュータによって構成される。4 人のプレーヤーによるクライアント/サーバー ゲームのトポロジを図解すると、次のようになる。

ゲームプレイは、各ユーザーのゲーム クライアントをサーバーと通信させることによって処理される。サーバーは、責任を持って、ほかのユーザーに情報を渡す。たとえば、あるユーザーが移動すると、メッセージがサーバーに送信される。するとサーバーは、ほかのプレーヤーにメッセージを送信して、ゲームの状態の変更を知らせる。サーバーには、いくつかの役割を割り当てることができる。

  • セッションのメッセージ送信ハブとして機能する。各コンピュータは、サーバーにメッセージを送信するだけでよい。サーバーは、ほかのすべてのユーザーを同期させるためのロジスティクスを処理する。この方法では、特に大きなゲームの場合、メッセージのトラフィックを大幅に削減することができる。
  • ゲームのホストとなる。サーバーは通常、ピアツーピアでセッション ホストが処理しなければならなかったタスクを引き受ける。
  • ゲームのいろいろな面をサポートする。サーバーは、多くの場合、ゲームのロジスティクスをサポートする以上の仕事を行う。多くのゲーム、特に大きなゲームでは、「ゲーム世界」を維持するための処理はほとんどサーバー上で実行される。ゲーム クライアントの主な仕事は、ユーザーの UI を処理することである。

普通、クライアント/サーバー ゲームは、ユーザーのコンピュータ上に常駐するロビー クライアント アプリケーションによってアレンジされ、起動する。ロビー クライアントは、ゲームをホストしているコンピュータと同じリモート コンピュータ上で実行されているロビー サーバー アプリケーションへのリンクとして機能する。ゲームが起動すると、ゲーム サーバー アプリケーションがホストとなり、新しいユーザーへの参加許可などのタスクを処理する。

クライアント/サーバー ゲームには、いくつかの利点がある。

  • 特に大規模なゲームでは、効率性が高い。特に、プレーヤーが増えてもメッセージ送信トラフィックの回線が増えるだけなので、ピアツーピアよりスケール的に優れている。大量のデータを扱うマルチプレーヤー ゲームには、クライアント/サーバー トポロジが必要である。
  • ユーザーのコンピュータの処理能力による制限を受けない。大きくて複雑な「ゲーム世界」を維持するため必要な処理の多くを 1 台の強力なコンピュータ上に配置し、ユーザーのコンピュータには UI を処理させることができる。
  • ゲームの重要な部分を中央のサイトで制御できる。たとえば、サーバー アプリケーションを変更するだけで、ゲームを更新したりバグを修正でき、多数のゲーム クライアントを更新する必要がない。

ただし、ピアツーピア ゲームは開発して出荷すれば実質上仕事が終わる。ゲーム クライアントはほとんど自己完結型である。クライアント/サーバー ゲームでは、通常のサポート サービスを提供する以外に、ユーザーに対してゲームの進行中もかかわることになる。また、ゲーム サーバー コンピュータや関連ソフトウェアと共に、すべてのメッセージ送信を処理するためのネットワーク リンクを、アプリケーションの製品寿命が続く限り、提供し、維持しなければならない。大量のデータを使用するマルチプレーヤー ゲームの場合、ほとんど、またはまったく休みなくサーバーを運用する必要があり、ユーザーのゲームプレイを中断するとユーザーを怒らせるというリスクもある。


DirectPlay ネットワーク通信

Microsoft® DirectPlay® の最大の機能は、ユーザーに、アプリケーションを基本となるネットワーク ハードウェアおよびソフトウェアから大きく隔離し、効率的で柔軟なメッセージング サポートを提供することである。状態更新を送信する必要がある場合、使用しているネットワークの種類に関係なく、ただ対応する DirectPlay API を呼び出せばよい。DirectPlay ネットワーク サービス プロバイダは、TCP/IP、IPX、モデム、シリアル リンクによる通信をサポートする。

ここでは説明するトピックは、次のとおりである。

  • DirectPlay トランスポート プロトコル
  • DirectPlay アドレス

注

DirectPlay はセキュリティによる通信はサポートしていない。

Microsoft Windows® 95 システムでモデムを使用するには、Telephony API (TAPI) のバージョン 2.0 をインストールする必要がある。TAPI 2.0 は http://www.microsoft.com/ からダウンロードできる。


DirectPlay トランスポート プロトコル

Microsoft® DirectPlay® ネットワーキング能力の中心は、DirectPlay プロトコルである。このトランスポート レイヤ プロトコルは、DirectPlay 8 用に完全にオーバーホールされ、すべてのメッセージングに使用されている。DirectPlay プロトコルは、送信中に何が起こっているかを心配する必要なく、送信側アプリケーションからターゲット アプリケーションへのデータ送信を簡単にすることに焦点を置いている。このプロトコルは、マルチプレーヤー ゲームの必要性に応じて調整された、次のような機能を提供する。

  • 信頼性の高いメッセージ配信と信頼性の低いメッセージ配信。信頼性の高いメッセージは、ターゲット アプリケーションがメッセージを受け取るまで再送信される。配信のタイプは、メッセージごとに割り当てることができる。
  • シーケンシャル メッセージ配信と非シーケンシャル メッセージ配信。シーケンシャル メッセージは、送信された順にターゲット アプリケーションに渡される。
  • メッセージの分割と再構築。メッセージ サイズがネットワークの容量を超える場合、DirectPlay は自動的にメッセージを分割して再構築する。
  • 混雑の制御。DirectPlay は、処理中のメッセージをターゲットが処理できるレベルに自動的に抑制する。この機能によって、ターゲットに処理できないほど大量のメッセージが送信されないようにする。
  • 送信の優先順位付け。重要なメッセージほど早く送信するために、DirectPlay では、メッセージに低、標準、高の優先度を割り当てることができる。優先度の高いメッセージが出力キューの正面に送信され、その後、標準優先度、優先度の低いメッセージが送信される。
  • メッセージのタイムアウト。現在処理中のメッセージ キューが、新しいメッセージによって押しやられた古いメッセージで滞ることがないように、DirectPlay では、すべてのメッセージにタイムアウト値を割り当てることができる。メッセージがタイムアウトすると、そのメッセージは、送信済みかどうかに関係なく、処理中のメッセージ キューから削除される。


DirectPlay アドレス

メッセージを配信するには、マルチプレーヤー ゲームの各参加者が一意のアドレスを持っている必要がある。アドレスは、アプリケーションを実行しているコンピュータを参照するか (デバイス アドレス)、アプリケーションが通信する必要のあるコンピュータを参照できる (ホスト アドレス)。

Microsoft® DirectPlay® アドレスは、URL 文字列の形態をとる。これらの文字列は、次に示す一般形式のスキーム、スキーム セパレータ、およびデータ文字列で構成される。

x-directplay:/[data string]

データ文字列にはいくつかの要素が含まれている。これらの要素は、発信者とターゲットが各種ネットワーク リンクを介して通信を行うために必要なものをすべて指定する。

使用にあたっては、URL 文字列は DirectPlay API メソッドとやり取りされる DirectPlay アドレス オブジェクトに埋め込まれる。URL 文字列を直接操作するか、またはアドレス オブジェクトによって公開されるメソッドを使って、データ文字列の各要素を個別に処理できる。


DirectPlay オブジェクトとの通信

Microsoft® DirectPlay® は、本質的には COM オブジェクトの 1 つのコレクションで構成されている。各オブジェクトは、DirectPlay のいろいろな面を制御するための 1 つ以上のインターフェイスを公開する。たとえば、DirectPlay ピア オブジェクト (CLSID_DirectPlay8Peer) は、ピアツーピア ゲームの管理に使用される。

DirectPlay オブジェクトと通信するには、オブジェクトのインターフェイスによって公開されるメソッドを呼び出す。たとえば、ピアツーピア ゲームで別のユーザーに何らかのデータを送信するには、DirectPlay8Peer.SendTo メソッドを呼び出してメッセージを送信する。そして DirectPlay によって、ターゲットにメッセージが届けられる。

DirectPlay は、1 つまたは複数のメッセージ ハンドラを介してユーザーのアプリケーションと通信する。メッセージ ハンドラは、アプリケーションに各種イベントを通知するために DirectPlay が呼び出すオブジェクトである。ドキュメントでは、オブジェクトによって公開されているメソッドを説明するが、オブジェクトのメソッドはすべてアプリケーションに実装する必要がある。そして起動時にオブジェクトを登録すると、DirectPlay がオブジェクトのメソッドを呼び出して、イベントが発生するとユーザーに知らせる。イベントに関する詳細情報は、メソッドのパラメータを通じて渡される。


DirectPlay ロビー サポート

ロビーは、プレーヤーがゲームに出会ったりアレンジできるようにすることを主目的とするアプリケーションである。ロビーは普通リモート コンピュータ上にあり、インターネットを介してアクセスされる。またロビー サーバーは、チャット ルームのホスティング、ニュースや情報のポスティング、商品の販売など、いろいろな機能も実行する。ロビー サーバーは便利な機能であり、マルチプレーヤー ゲームのアレンジに一般的に使用されるが、必須条件ではない。またマルチプレーヤー ゲームは、ロビー クライアントどうしの直接通信によってアレンジすることもできる。

普通、ゲームがロビーと対話できるようにするためには、3 つのコンポーネントが必要である。

  • ロビー サーバー
  • ロビー クライアント
  • ロビー対応ゲーム

Microsoft® DirectPlay® は、ロビー サーバー アプリケーションの実装方法は指定しない。代わりに、DirectPlay はロビー クライアントのサポートを提供する。ロビー クライアントは、ロビー サーバー ベンダーによって実装され、各ユーザーのシステムにインストールされるアプリケーションである。これは、ユーザーとロビーのリンクとして有用である。このような通信を直接処理することもできるが、そのためには自分のゲームを起動するすべてのロビーの実装の詳細を知っていなければならない。

ロビー クライアント アプリケーションは、適切なプロトコルを使用して、関連するロビー サーバーとの通信の詳細を処理する。ロビー クライアントは、DirectPlay インターフェイスによってユーザーやユーザーのゲーム アプリケーションと通信する。そのとき、DirectPlay はアプリケーションにメッセージを渡す。またアプリケーションは、DirectPlay インターフェイスを使ってロビー クライアントにメッセージを渡すことができる。

ロビーは、実質的にどんなアプリケーションでも起動できる。ただし、アプリケーションがロビー起動の利点をフル活用するには、いくつかの特定のロビー アウェア コンポーネントを持っている必要がある。特に、ロビー対応アプリケーションは、セッション全体を通してロビー クライアントと通信することができる。アプリケーションがロビー対応として登録されている場合、ロビー クライアントは、ホストの移行など、ゲーム状態のいろいろな変更に対する更新も自動的に受け取る。


DirectPlay 音声通信

現在の傾向はチーム ベースのマルチプレーヤー ゲームであるため、プレーヤー同士の通信がゲームプレーの不可欠な部分となっている。歴史的にプレーヤー同士の通信はテキスト ベースに制約されてきた。プレーヤーはチームメイト宛てのメッセージをキーボードから入力していた。テキストベースの通信は、スピードの遅いターンベースのゲームには適しているものの、リアルタイム ゲームでは不便でしかない。キーボード入力の遅いプレーヤーがゲームで不利になるばかりでなく、ゲームが創出しようとしているリアリティが著しく妨げられる。この問題の明白な解決策は、通信手段として音声を使用することである。この解決策は、トレーニングの必要がなく、ゲーム自体への集中を高める。

Windows プラットフォームでは、ビデオ ゲーム開発者向けに、リアルタイム音声会議の実装に必要なすべてのツールが用意されているが、ゲーム開発者の側に多大な労力が要求される。このことは、極端に帯域幅の少ない状況に対応できる圧縮技術の権利を取得する費用と困難さと共に、ゲームにおける音声使用の広がりを妨げてきた。

Microsoft® DirectPlay® 8.0 は、ゲーム開発者に、最小限の労力で使用できる堅牢なリアルタイム音声会議システムを提供する。


DirectPlay について

Microsoft® DirectPlay® ドキュメントのこのセクションでは、アプリケーションでの DirectPlay API の使い方を理解するために必要な基本的背景について説明する。

  • ピアツーピア セッション
  • クライアント/サーバー セッション
  • DirectPlay のロビー
  • ネットワーキングの基本
  • DirectPlay コールバック関数とマルチスレッドに関する問題
  • DirectPlay Voice について


ピアツーピア セッション

ピアツーピア セッションは、ネットワークで接続されたユーザーの集合から構成される。ゲームの準備と起動にはロビー サーバーを使用することがあるが、ゲームの実行に必要なメッセージングはユーザー間で直接やり取りする。ロビー サーバーとの通信は、参加者リストの更新といった限られた目的にのみ使用する。

ピアツーピアのゲームでは、ゲームの実行に必要なことがすべてクライアント ソフトウェアに属する。サーバーが関係しないため、ゲーム全体を作成し、維持するために必要な処理は、すべてクライアント アプリケーションで行わなければならない。このドキュメントでは、Microsoft® DirectPlay® によるロビー可能なピアツーピア ゲームの基本的原理を説明する。ピアツーピア アプリケーションの簡単な実例については、SDK 付属の SimplePeer アプリケーションを参照すること。

  • ピアツーピア セッションの開始
  • ピアツーピア セッションに使用するサービス プロバイダの選択
  • ピアツーピア セッションに使用するホストの選択
  • ピアツーピア セッションへの接続
  • ピアツーピア セッションの管理
  • ホストの移行
  • ピアツーピア ゲームの通常のプレー
  • ピアツーピア セッションからの離脱
  • ピアツーピア セッションの終了


ピアツーピア セッションの開始

ピアツーピア ゲームは、ユーザーが直接起動することも、ユーザーのコンピュータに常駐する "ロビー クライアント" アプリケーションから "ロビー起動" することもできる。このドキュメントでは、ロビー クライアントと通信できるロビー可能なゲームを想定して説明する。

実行すべき最初のステップの 1 つは、ゲームがロビー起動で起動されているかどうかを判断することである。これには、DirectPlay8LobbiedApplication オブジェクトと DirectPlay8LobbyEvent オブジェクトを作成する。DirectPlay8LobbiedApplication.RegisterMessageHandler を呼び出して、DirectPlay8LobbyEvent オブジェクトを Microsoft® DirectPlay® に登録する。DirectPlay8LobbyEvent オブジェクトは、基本的には、ロビー対象アプリケーションからは直接、ロビー クライアントとロビーからは間接的に、通知を受けるイベント ハンドラである。イベント ハンドラは、DirectPlay から提供されないので、アプリケーションで実装する必要がある。詳細については、リファレンス ドキュメントを参照すること。

アプリケーションがロビー起動で起動されている場合は、DirectPlay から DirectPlay8LobbyEvent.Connect メソッドが呼び出される。dlNotify パラメータには、セッション メンバのアドレス オブジェクトといった接続情報が付いた DPL_MESSAGE_CONNECT 型が格納される。

また、DirectPlay8Peer オブジェクトを作成し、DirectPlay8Peer.RegisterMessageHandler を呼び出して DirectPlay8Event 通知ハンドラ オブジェクトを登録する必要もある。これらのオブジェクトが、DirectPlay およびセッション内の残りメンバとの主な通信手段となる。セッションに複数のプレーヤーを参加させるためには、これらのオブジェクトのインスタンスを、プレーヤーごとに作成する必要がある。


ピアツーピア セッションに使用するサービス プロバイダの選択

この場合、使用中のネットワーク接続がサービス プロバイダとなる。TCP/IP またはモデムのサービス プロバイダを使用するゲームが多いが、Microsoft® DirectPlay® はシリアル接続と IPX 接続にも対応している。

ユーザーがロビー クライアントでセッションに接続されている場合には、DirectPlay8LobbyEvent.Connect メソッドに付属する DPL_MESSAGE_CONNECT 構造体を調べれば、適切なサービス プロバイダを判断できる。それ以外の場合、使用するサービス プロバイダを判断するには、ユーザーに照会するなどの方法をとる必要がある。ピア オブジェクトの DirectPlay8Peer.GetServiceProvider メソッドを使って、利用可能なサービス プロバイダを列挙することもできる。

サービス プロバイダを選択すると、ユーザーの DirectPlay アドレス オブジェクト (デバイス アドレス) を作成できるようになる。DirectPlay の多くのメソッドでは、このアドレスを使ってデバイスを識別する。DirectPlay アドレスとアドレス オブジェクトの詳細については、｢DirectPlay アドレシング｣を参照すること。


ピアツーピア セッションに使用するホストの選択

ピアツーピア ゲームには、個々のユーザーが直接やり取りして処理できる要素も多いが、単独のオーナーが担当すべき作業もある。これらの作業は、ゲーム ホストが行う。セッションに加わるには、セッション ホストのアドレスを知っている必要がある。通常、ホストの選択はロビー サーバーを通じて行う。この場合、ユーザーのアプリケーションがセッションに接続されると、Microsoft® DirectPlay® が DirectPlay8LobbyEvent.Connect メソッドを呼び出したときに接続設定が届き、その接続設定にホストのアドレス オブジェクトが含まれている。セッション ホストを調べるには、以下の処理を実行する。

  • DPL_CONNECTION_SETTINGS 構造体の dwFlags メンバを調べる。この構造体は、dlNotify パラメータとして渡される DPL_MESSAGE_CONNECTION_SETTINGS に含まれている。このメンバが DPLCONNECTSETTINGS_HOST に設定されている場合は、使用中のシステムがホストである。
  • DPLCONNECTSETTINGS_HOST フラグが設定されていない場合は、pdp8HostAddress メンバからホストのアドレスを取得できる。

また、自分がセッション ホストであることを公表して、(たとえば LAN サブネット上で) ある要素を全要素にコピーするセッションを作成することもできる。これには、DirectPlay8Peer.SetPeerInfo を呼び出してプレーヤー名を設定してから、DirectPlay8Peer.Host を呼び出して自分がホストの候補であることを公表する。ゲームの構成は、IDirectPlay8Peer.Host の pdnAppDesc のパラメータで渡す DPN_APPLICATION_DESC 構造体に値を割り当てて指定する。

利用可能なセッションとホストをユーザーに知らせるには、DirectPlay8Peer.EnumHosts を呼び出せば、利用可能なホストを列挙できる。ユーザーがセッションを選択すると、接続を要求できるようになる。


ピアツーピア セッションへの接続

セッション ホストでない限り、プレーヤーをセッションに接続する必要がある。これには、セッション ホストのアドレスが必要になる。アプリケーションがロビー クライアントから接続されている場合は、DirectPlay8LobbiedApplication.GetConnectionSettings を呼び出せば、ホストのアドレスを取得できる。ホストのアドレスは、利用可能なホストを列挙して取得することもできる。列挙から返される情報には、各ホストのアドレスと、関連付けられたセッションを記述する DPN_APPLICATION_DESC 構造体が含まれる。

セッションへの参加を要求するには、DirectPlay8Peer.SetPeerInfo を呼び出してプレーヤー名を設定してから、選択されたホストのアドレスを指定して DirectPlay8Peer.Connect を呼び出すことによりセッションに接続する。

プレーヤーがセッションへの参加を試みると、Microsoft® DirectPlay® からホストの DirectPlay8Event.IndicateConnect メソッドが呼び出される。プレーヤーの参加を許可する場合は、復帰前にメソッドの fRejectMsg パラメータを FALSE に設定する。要求を拒否する場合は、fRejectMsg を TRUE に設定する。どちらの場合も、プレーヤーの DirectPlay8Event.ConnectComplete メソッドが呼び出されて応答が渡される。ホストが接続を受け付けた場合は、DPNMSG_CONNECT_COMPLETE 型の hResultCode メンバが 0 に設定される。要求が拒否された場合、または何らかの理由で要求が失敗した場合には、hResultCode にエラー コードが設定される。

新しいプレーヤーが接続されると、DirectPlay は、ホストを含むセッション メンバぞれぞれについて DirectPlay8Event.CreatePlayer を呼び出して、新しいプレーヤーを公表する。lPlayerID パラメータには、プレーヤーへのメッセージ送信に使用するプレーヤー ID が格納されている。


ピアツーピア セッションの管理

セッション ホストでは、以下のようなセッション管理を行わなければならない。

  • セッション メンバとそのネットワーク アドレスのリストを管理する。
  • 新しいユーザーのセッション参加を許すかどうかを判断する。
  • 新しいユーザーがセッションに加わったら、メンバ全員に通知し、新しいユーザーのアドレスを渡す。
  • 新しいユーザーに現在のゲームの状態を提供する。
  • ユーザーがセッションを抜けたら、ユーザー全員に通知する。

プレーヤーがセッションへの参加を試みると、Microsoft® DirectPlay® からホストの DirectPlay8Event.IndicateConnect メソッドが呼び出される。プレーヤーの参加を許可する場合は、fRejectMsg を FALSE に設定する。要求を拒否する場合は、fRejectMsg を FALSE 以外の値に設定する。どちらの場合も、プレーヤーの DirectPlay8Event.ConnectComplete メソッドが呼び出されて、要求への応答が渡される。

ホストはプレーヤーをセッションから削除できる。これには、DirectPlay8Peer.DestroyPeer を呼び出す。ホスト以外のメンバは、このメソッドを呼び出すと失敗する。プレーヤーがほかのプレーヤーをセッションから削除するには、要求をホストに送信し、ホスト側で処理させる必要がある。


ホストの移行

ホストは、セッションの初期メンバでなければならないが、セッションの終了前に抜けてもよい。ホストがセッションを抜けると、以下のどちらかの結果になる。

  • セッションが終了する。
  • ホストが "移行" して別のユーザーがホストになる。

ホストが移行可能かどうかはセッションによって異なる。ホストの移行を有効にするには、ゲームのセットアップ時に、セッションの主催者が DPN_APPLICATION_DESC 型の dwFlags メンバに DPNSESSION_MIGRATE_HOST フラグを設定する必要がある。このフラグが設定されていない場合は、ホストが抜けるか、またはホストとセッションの接続が失われると、セッションが終了する。

DPNSESSION_MIGRATE_HOST フラグが設定されていても、ホストは DirectPlay8Peer.TerminateSession を呼び出してセッションを強制終了できる。

DPNSESSION_MIGRATE_HOST フラグが設定されている場合には、ホストがセッションを抜けると、Microsoft® DirectPlay® が新しいセッション ホストを選択する。DirectPlay は、新しいホストの ID を指定して残りのセッション メンバ全員の DirectPlay8Event.HostMigrate メソッドを呼び出す。


ピアツーピア ゲームの通常のプレー

Microsoft® DirectPlay® のメッセージは、基本的には、セッション内のメンバに送信されるゲーム関連のデータ ブロックである。DirectPlay は、データ ブロックの内容や形式を限定せずに、ユーザーどうしがデータをやり取りするためのメカニズムのみを提供する。ゲームの進行中には、通常、各セッション メンバから残りのセッション メンバ全員に対して、メッセージが間断なく送信される。これらのメッセージの主な目的は、各ユーザーのアプリケーションに同じ UI を表示するために、ゲームの状態の同期をとることにある。ただし、メッセージは、これに限らずゲーム固有の多様な目的に使用できる。

ゲーム (特に変化の速いゲーム) では、メッセージングを慎重に管理しなければならない場合が多い。DirectPlay は、流出するメッセージを、ターゲットが処理できるレベルに減速 (スロットリング) する。重要なメッセージを確実に届けるため、メッセージをあまり高速で送信しないように注意しなければならない。DirectPlay での効率的なメッセージング処理については、｢ネットワーキングの基本｣を参照すること。

ほかのセッション メンバにメッセージを送信するには、DirectPlay8Peer.SendTo を呼び出す。DirectPlay が、データを指定してそのメンバの DirectPlay8Event.Receive メソッドを呼び出す。特定のプレーヤーにメッセージを送信するには、DirectPlay8Event.CreatePlayer メソッドが呼び出されたときに受け取ったプレーヤー ID を、idSend パラメータに設定する。また、idSend を DPNID_ALL_PLAYERS_GROUP に設定すれば、セッション内のプレーヤー全員にメッセージを送信できる。プレーヤーのグループを定義すると、SendTo を 1 回呼び出すだけで、グループのメンバ全員にメッセージを送信できる。

注 ほかのユーザーに情報を送信するには、DirectPlay8Peer.SetPeerInfo メソッドを使用してもよい。DirectPlay が、この情報を指定してそれらのメンバの DirectPlay8Event.InfoNotify メソッドを呼び出す。ただし、この送信方法はあまり効率的でないので、通常のメッセージングでは使用しないこと。

グループの使用

多くのゲームは、プレーヤーをグループ分けできるようになっている。たとえば戦略型ゲームでは、通常、プレーヤーを複数のグループに分け、グループ単位で指示を出すことができる。Microsoft® DirectPlay® でも、プレーヤー グループを編成できる。DirectPlay のグループは、基本的にはメッセージングを簡略化する手段である。グループを定義すると、DirectPlay8Peer.SendTo を 1 回呼び出すだけで、グループ メンバ全員にメッセージを送信できるようになる。DirectPlay のグループは、通常はゲームで定義されるグループに対応するが、グループ作成の目的が限定されているわけではない。

DirectPlay のグループを作成するには、DirectPlay8Peer.CreateGroup を呼び出す。DirectPlay が、詳細を指定してセッション メンバ全員の DirectPlay8Event.CreateGroup メソッドを呼び出す。メソッドの lGroupID パラメータには、グループにメッセージを送信するために使用するグループ ID が設定される。

グループを作成したら、次に DirectPlay8Peer.AddPlayerToGroup を呼び出してプレーヤーを追加する。この結果、DirectPlay が、新しくプレーヤーが追加されたグループの ID を指定して、メンバ全員の DirectPlay8Event.AddRemovePlayerGroup を呼び出す。

グループを確立すると、そのグループにデータを送信できるようになる。これには、idSend パラメータにグループ ID を設定して DirectPlay8Peer.SendTo を呼び出す。この結果、DirectPlay が、データを指定してグループ メンバ全員の DirectPlay8Event.Receive メソッドを呼び出す。

グループからプレーヤーを削除するには、DirectPlay8Peer.RemovePlayerFromGroup を呼び出す。DirectPlay が、プレーヤーの ID を指定してセッション メンバの DirectPlay8Event.AddRemovePlayerGroup メソッドを呼び出す。

最後に、グループを使い終わったら、DirectPlay8Peer.DestroyGroup を呼び出せば破棄できる。DirectPlay が、グループ ID を指定してセッション メンバ全員の DirectPlay8Event.DestroyGroup メソッドを呼び出す。


ピアツーピア セッションからの離脱

セッションを抜けるには、DirectPlay8Peer.Close を呼び出して接続を終了する。Microsoft® DirectPlay® が、lPlayerID パラメータにプレーヤーの ID を設定して、セッション メンバの DirectPlay8Event.DestroyPlayer メソッドを呼び出す。

セッション ホスト自身がセッションを抜けると、セッションも終了する。ただし、セッションがホストの移行を許すように構成されている場合は例外である。詳細については、｢ホストの移行｣を参照すること。


ピアツーピア セッションの終了

使い終わったセッションは、ホストが DirectPlay8Peer.TerminateSession を呼び出して終了しなければならない。このメソッドは、ホストの移行が有効になっていても、ホスト移行をせずにセッションを終了する。Microsoft® DirectPlay® が、セッション メンバ全員の DirectPlay8Event.TerminateSession メソッドを呼び出して通知する。この後、必要なクリーンアップがあれば実行する。別のセッションを開始するには、DirectPlay8Peer.Close を呼び出してから DirectPlay8Peer.RegisterMessageHandler を呼び出す必要がある。

DirectPlay8LobbiedApplication.SetAppAvailable の呼び出しにより、アプリケーションが接続可能であると登録されている場合には、ロビー クライアントは、アプリケーションの DirectPlay8LobbyEvent.Connect メソッドを呼び出して、実行中のアプリケーションと新しいセッションの接続を試みることができる。この場合はまず、DirectPlay8Peer.Close を呼び出してから DirectPlay8.RegisterMessageHandler を呼び出しておく必要がある。


クライアント/サーバー セッション

クライアント/サーバー セッションは、中心となるサーバーと、それに接続されたプレーヤー (つまりクライアント) の集合から構成される。Microsoft® DirectPlay® に関する限り、クライアントの情報はサーバーだけが把握し、クライアントがほかのクライアントについて知ることはない。ゲームの実行に必要なメッセージは、各クライアントとサーバーの間でやり取りされる。ピアツーピア セッションの場合と異なり、クライアント間で直接にメッセージングを行うことはできない。

クライアント/サーバー セッションでは、以下の 2 つのまったく異質なアプリケーションが必要になる。

  • リモート サーバーで動作するサーバー アプリケーション。最低限でも、中心となるメッセージング ハブおよびゲーム ホストとしての機能を持つ。サーバーは、クライアントから流入するすべてのメッセージを受信して処理し、適切なメッセージを返信する必要がある。クライアントから別のクライアントへのデータ転送は、すべてサーバー アプリケーション側で処理する必要がある。
  • 各プレーヤーのコンピュータで動作するクライアント アプリケーション。このアプリケーションの主な機能は、UI を処理し、サーバーとの間でプレーヤーのゲームの状態の同期をとることである。

セッションの一部の要素は、これらのアプリケーションの一方でしか処理できない。たとえば、プレーヤーのビデオ表示の更新は、クライアント アプリケーションでなければ実行できない。しかし、ゲーム全体を維持するために必要な処理の多くの要素は、少なくとも原則的には、どちらのアプリケーションでも実行できる。効率的なクライアント/サーバー ゲームを作成するには、個々の処理を 2 つのアプリケーションにどのように振り分けるかを、慎重に判断する必要がある。

このドキュメントでは、クライアント/サーバー ゲームの基本的な原理と、クライアント/サーバー アプリケーションの実装方法の概要を説明する。

  • クライアント/サーバー セッションの開始
  • クライアント用サービス プロバイダの選択
  • クライアント/サーバー ホストの選択
  • クライアント/サーバー セッションへの接続
  • クライアント/サーバー セッションの管理
  • クライアント/サーバー ゲームの通常のプレー
  • クライアント/サーバー セッションからの離脱
  • クライアント/サーバー セッションの終了


クライアント/サーバー セッションの開始

クライアント/サーバー ゲームは、ロビーを通じて起動することも、サーバー アプリケーションから直接起動することもできる。

サーバー アプリケーション

クライアント/サーバー ゲームは、ロビーを通じて準備されることが多い。サーバーを起動する最も直接的な方法は、サーバーを "ロビー可能" アプリケーションとして実装することである。このアプローチでは、サーバーを起動する手段が提供され、セッション進行中にサーバーとロビーが通信を行うことができる。詳細については、｢DirectPlay のロビー｣を参照すること。

サーバーを直接起動してから、そのサーバーが利用可能であることを公表し、クライアントからの接続を待つこともできる。詳細については、｢クライアント/サーバー ホストの選択｣を参照すること。

サーバー アプリケーションは、起動されたら、その DirectPlay8Event 通知ハンドラ オブジェクトを登録しなければならない。DirectPlay8Event オブジェクトは、基本的には Microsoft® DirectPlay® から通知を受けるイベント ハンドラである。イベント ハンドラは、DirectPlay から提供されないので、アプリケーションで実装する必要がある。詳細については、リファレンス ドキュメントを参照すること。また、DirectPlay8Server.SetServerInfo を呼び出して現在のゲームの記述も行わなければならない。このメソッドが呼び出されていないと、クライアントがサーバーに接続できない。

クライアント アプリケーション

実行すべき最初のステップの 1 つは、ゲームがロビー起動で起動されているかどうかを判断することである。これには、DirectPlay8LobbiedApplication オブジェクトと DirectPlay8LobbyEvent オブジェクトを作成する。DirectPlay8LobbiedApplication.RegisterMessageHandler を呼び出して、DirectPlay8LobbyEvent オブジェクトを Microsoft® DirectPlay® に登録する。DirectPlay8LobbyEvent オブジェクトは、基本的には、ロビー対象アプリケーションからは直接、ロビー クライアントとロビーからは間接的に、通知を受けるイベント ハンドラである。イベント ハンドラは、DirectPlay から提供されないので、アプリケーションで実装する必要がある。詳細については、リファレンス ドキュメントを参照すること。

アプリケーションがロビー起動で起動されている場合は、DirectPlay から DirectPlay8LobbyEvent.Connect メソッドが呼び出される。dlNotify パラメータには、セッション メンバのアドレス オブジェクトといった接続情報が付いた DPL_MESSAGE_CONNECT 型が格納される。

また、DirectPlay8Client オブジェクトを作成し、DirectPlay8Client.RegisterMessageHandler を呼び出して DirectPlay8Event 通知ハンドラ オブジェクトを登録する必要もある。これらのオブジェクトが、サーバーとの主な通信手段となる。


クライアント用サービス プロバイダの選択

この場合、使用中のネットワーク接続がサービス プロバイダとなる。TCP/IP またはモデムのサービス プロバイダを使用するゲームが多いが、Microsoft® DirectPlay® はシリアル接続と IPX 接続にも対応している。

ユーザーがロビー クライアントでセッションに接続されている場合には、DirectPlay から DirectPlay8LobbyEvent.Connect が呼び出されたときに受け取った DPL_CONNECTION_SETTINGS 型を調べれば、適切なサービス プロバイダを判断できる。それ以外の場合、使用するサービス プロバイダを判断するには、ユーザーに照会するなどの方法をとる必要がある。クライアント オブジェクトの DirectPlay8Client.GetServiceProvider メソッドを使用すると、利用可能なサービス プロバイダを列挙できる。詳細については、｢DirectPlay 列挙の使い方｣を参照すること。

サービス プロバイダを選択すると、ユーザーの DirectPlay アドレス オブジェクト (デバイス アドレス) を作成できるようになる。DirectPlay の多くのメソッドでは、このアドレスを使ってデバイスを識別する。DirectPlay アドレスとアドレス オブジェクトの詳細については、｢DirectPlay アドレシング｣を参照すること。


クライアント/サーバー ホストの選択

セッションのホストは、当然、サーバー アプリケーションが担当する。セッションに加わるには、クライアント アプリケーションでホスト サーバーのアドレスを判断する必要がある。通常、ホストの選択はロビー サーバーを通じて行う。この場合、ユーザーのアプリケーションがセッションに接続されると、DirectPlay8LobbyEvent.Connect メソッドが呼び出されたときに接続設定が届き、その接続設定に接続 ID とホストのアドレスが含まれている。

また、IP または IPX サービス プロバイダを使用しているサーバーでは、そのサーバーがセッション ホストであることを公表して、(たとえば LAN サブネット上で) "ある要素を全要素にコピーするセッション" を作成することもできる。ある要素を全要素にコピーするセッションを作成するには、DirectPlay8Server.SetServerInfo を呼び出してサーバー情報を設定する。次に DirectPlay8Server.Host を呼び出して、セッション自体がセッション ホストであることを公表する。ゲームの構成は、DirectPlay8Server.Host の AppDesc のパラメータで渡す DPN_APPLICATION_DESC 構造体に値を割り当てて指定する。

利用可能なセッションとホストをユーザーに知らせるには、クライアント アプリケーションで DirectPlay8Client.EnumHosts を呼び出せば、利用可能なホストを照会できる。ユーザーがホストを選択すると、接続を要求できるようになる。


クライアント/サーバー セッションへの接続

すべてのクライアントは、ホストに接続して明示的にセッションに加わる必要がある。このことは、ロビーを通じて準備されたセッションでも同じである。接続により、クライアントがセッションのメンバになり、クライアントとの通信に必要な情報がホストに提供される。ホストでは、接続要求を受け付けることも拒否することもできる。

サーバー アプリケーション

クライアントがセッションへの参加を試みると、Microsoft® DirectPlay® からサーバーの DirectPlay8Event.IndicateConnect メソッドが呼び出される。プレーヤーの参加を許可する場合は、復帰前にメソッドの fRejectMsg パラメータを FALSE に設定する。要求を拒否する場合は、fRejectMsg を TRUE に設定する。どちらの場合も、プレーヤーの DirectPlay8Event.ConnectComplete メソッドが呼び出されて応答が渡される。ホストが接続を受け付けた場合は、DPNMSG_CONNECT_COMPLETE 型の hResultCode メンバが 0 に設定される。要求が拒否された場合、または何らかの理由で要求が失敗した場合には、hResultCode にエラー コードが設定される。

プレーヤーがセッションへの接続に成功すると、DirectPlay が、新しいプレーヤーの ID (DPNID) を指定して、サーバーと全クライアントの DirectPlay8Event.CreatePlayer メソッドを呼び出す。

クライアント アプリケーション

セッションに接続するには、セッション ホストのアドレスが必要になる。アプリケーションがロビー クライアントから接続されている場合は、DirectPlay8LobbiedApplication.GetConnectionSettings を呼び出せば、ホストのアドレスを取得できる。

セッション ホストのアドレスがわからない場合、IP または IPX サービス プロバイダを使用しているなら、DirectPlay8Client.EnumHosts を呼び出して利用可能なホストを列挙すれば、ある要素を全要素にコピーするセッションを調べることができる。ホストのアドレスは、利用可能なホストを列挙して取得することもできる。列挙から返される情報には、各ホストのアドレス、ホストとの通信に使用するデバイス、および関連付けられたセッションを記述する DPN_APPLICATION_DESC 型が含まれる。

セッションへの参加を要求するには、DirectPlay8Client.SetClientInfo を呼び出してプレーヤー名を設定してから、選択されたホストのアドレスを指定して DirectPlay8Client.Connect を呼び出すことによりセッションに接続する。

Microsoft® DirectPlay® から、ホストの応答を指定して DirectPlay8Event.ConnectComplete メソッドが呼び出される。ホストが接続を受け付けた場合は、DPNMSG_CONNECT_COMPLETE 型の hResultCode メンバが 0 に設定される。要求が拒否された場合、または何らかの理由で要求が失敗した場合には、hResultCode にエラー コードが設定される。


クライアント/サーバー セッションの管理

ホストとして、サーバーにはセッションの進行を管理する義務がある。詳細はアプリケーションの設計によって異なるが、セッション ホストが少なくとも以下の作業を行わなければならないことは共通である。

  • セッション メンバとそのネットワーク アドレスのリストを管理する。この作業の一部は Microsoft® DirectPlay® で行われるが、サーバー アプリケーションで管理しなければならないプレーヤー データは、通常、DirectPlay から提供されるデータだけではない。
  • 新しいユーザーのセッション参加を許すかどうかを判断する。
  • 新しいユーザーに現在のゲームの状態を提供する。

プレーヤーがセッションへの参加を試みると、DirectPlay からホストの DirectPlay8Event.IndicateConnect メソッドが呼び出される。プレーヤーの参加を許可する場合は、fRejectMsg を FALSE に設定する。要求を拒否する場合は、fRejectMsg を FALSE 以外の値に設定する。どちらの場合も、プレーヤーの DirectPlay8Event.ConnectComplete メソッドが呼び出されて、要求への応答が渡される。

ホストはプレーヤーをセッションから削除できる。これには、DirectPlay8Server.DestroyClient を呼び出す。


クライアント/サーバー ゲームの通常のプレー

Microsoft® DirectPlay® のメッセージは、基本的には、クライアントとサーバーの間でやり取りされるゲーム関連のデータ ブロックである。DirectPlay は、データ ブロックの内容や形式を限定せずに、データをやり取りするためのメカニズムのみを提供する。ゲームの進行中には、通常、各クライアントとサーバーの間で、メッセージが間断なくやり取りされる。これらのメッセージの主な目的は、各ユーザーのアプリケーションに同じ UI を表示するために、ゲームの状態の同期をとることにある。ただし、メッセージは、これに限らずゲーム固有の多様な目的に使用できる。

ゲーム (特に変化の速いゲーム) では、メッセージングを慎重に管理しなければならない場合が多い。DirectPlay は、流出するメッセージを、ターゲットが処理できるレベルに減速 (スロットリング) する。重要なメッセージを確実に届けるため、メッセージをあまり高速で送信しないように注意しなければならない。DirectPlay での効率的なメッセージング処理については、｢ネットワーキングの基本｣を参照すること。

サーバー アプリケーション

クライアントにメッセージを送信するには、DirectPlay8Server.SendTo を呼び出す。DirectPlay が、データを指定してクライアントの DirectPlay8Event.Receive メソッドを呼び出す。

クライアント アプリケーション

サーバーにメッセージを送信するには、DirectPlay8Client.Send を呼び出す。DirectPlay が、データを指定してサーバーの DirectPlay8Event.Receive メソッドを呼び出す。

注 DirectPlay にはクライアント間の通信メカニズムはなく、クライアントとサーバーの間の通信メカニズムだけが用意されている。クライアント間の通信は、すべてサーバー アプリケーションで実装する必要がある。

グループの使用

多くのゲームは、プレーヤーをグループ分けできるようになっている。たとえば、チーム対戦型ゲームでは、チームのプレーヤー全員を 1 つのグループのメンバにしてもよい。DirectPlay では、クライアント/サーバー ゲームのサーバーが、プレーヤーのグループを作成できる。DirectPlay のグループは、通常はゲームで定義されるグループに対応するが、グループ作成の目的が限定されているわけではない。DirectPlay のグループは、基本的にはメッセージングを簡略化する手段である。グループを定義すると、DirectPlay8Server.SendTo を 1 回呼び出すだけで、グループ メンバ全員にメッセージを送信できるようになる。

DirectPlay のグループを作成するには、DirectPlay8Server.CreateGroup を呼び出す。DirectPlay から、詳細を指定して DirectPlay8Event.CreateGroup メソッドが呼び出される。この通知には、グループにメッセージを送信するために使用するグループ ID が含まれる。グループを作成したら、次に DirectPlay8Server.AddClientToGroup を呼び出してプレーヤーを追加する。

グループを確立すると、そのグループにデータを送信できるようになる。これには、idSend パラメータにグループ ID を設定して DirectPlay8Server.SendTo を呼び出す。この結果、DirectPlay が、データを指定してグループ メンバの DirectPlay8Event.Receive メソッドを呼び出す。

グループからプレーヤーを削除するには、DirectPlay8Server.RemoveClientFromGroup を呼び出す。最後に、グループを使い終わったら、DirectPlay8Server.DestroyGroup を呼び出せば破棄できる。


クライアント/サーバー セッションからの離脱

クライアントがセッションを抜けるには、DirectPlay8Client.Close を呼び出す。この結果、Microsoft® DirectPlay® がサーバーの DirectPlay8Event.DestroyPlayer メソッドを呼び出して通知する。


クライアント/サーバー セッションの終了

クライアント/サーバー セッションを終了するには、サーバーが DirectPlay8Server.Close を呼び出す。クライアント/サーバー セッションの場合、ホストは移行しないので、このメソッドによりすべての接続が終了し、セッション自体が終了する。この結果、Microsoft® DirectPlay® がクライアントの DirectPlay8Event.TerminateSession メソッドを呼び出して通知する。

DirectPlay が、サーバー自体を含む各プレーヤーについてサーバーの DirectPlay8Event.DestroyPlayer メソッドを呼び出す。DirectPlay8Server.Close は、同期メソッドであり、DirectPlay8Event.DestroyPlayer メソッドの呼び出しがすべて処理されるまで復帰しない。DirectPlay8Server.Close から復帰すると、サーバー アプリケーションを安全にシャットダウンできるようになる。

サーバーがセッションを閉じるとき、すべての接続されているプレーヤから DPN_MSGID_DESTROY_PLAYER を受け取る。サーバーは接続を解除していることを知っているので、これは通常の振る舞いであり、構成された構造体の dwReason メンバには DPNDESTROYPLAYERREASON_NORMAL が設定される。DPNDESTROYPLAYERREASON_SESSIONTERMINATED 値は予期せぬ接続解除の場合にのみ設定される。


DirectPlay のロビー

ロビーとは、ユーザーがマルチプレーヤー ゲームを準備できるようにすることを主な目的とするアプリケーションである。ロビーは、通常、リモート サーバー上で動作するアプリケーションである。ユーザーは、(主にインターネット経由で) ロビーにアクセスし、ゲーム セッションを設定するか、またはだれかが開始したセッションに加わる。この結果、ロビー アプリケーションがグループの各ゲーム アプリケーションを起動し、ゲームが始まる。

マルチプレーヤー ゲームの多くはロビーを通じて準備されるので、Microsoft® DirectPlay® ベースのゲームの多くは、ロビー アプリケーションと対話できなければならない。逆に、多くのロビーは DirectPlay ベースのゲームをサポートする必要があるので、ロビー アプリケーションはゲーム アプリケーションと対話できなければならない。このドキュメントでは、Microsoft DirectX® のゲームがロビーと対話できるようにする方法 (およびロビーが Microsoft DirectX® のゲームと対話できるようにする方法) を説明する。

  • DirectPlay のロビー アーキテクチャ
  • ロビー サーバー
  • ロビー クライアント
  • ロビー可能アプリケーション


DirectPlay のロビー アーキテクチャ

Microsoft® DirectPlay® に基づくマルチプレーヤー ゲームのセッションを準備し、管理するプロセスには、独立した 5 つの構成要素が関係している。ロビー サーバー アプリケーションは、通常、リモート サーバーに常駐し、インターネットを通じてアクセスされるサードパーティ アプリケーションである。残りの 4 つの構成要素は、各プレーヤーのコンピュータにインストールされる。

  • ロビー クライアント。ロビー クライアントは、ロビー サーバーと通信するサードパーティ アプリケーションである。ロビー クライアントは、DirectPlay ロビー クライアント オブジェクトを通じて、ユーザーのゲーム アプリケーションとも通信する。
  • ロビー可能ゲーム アプリケーション。ロビー可能ゲーム アプリケーションは、DirectPlay ロビー対象アプリケーション オブジェクトを使ってロビー クライアントと通信し、ロビー クライアントを通じてロビー サーバーと通信する、サードパーティ アプリケーションである。
  • DirectPlay ロビー クライアント オブジェクト。
  • DirectPlay ロビー対象アプリケーション オブジェクト。

これらの 2 つの DirectPlay オブジェクトは、ゲーム アプリケーションとロビー クライアントの間のリンクとして機能する。これらのオブジェクトは、プライベートなインターフェイスを通じてやり取りする。次のグラフィックは、これらの構成要素がリンクされ、データをやり取りする様子を示している。


ロビー サーバー

ロビー サーバーは、プレーヤーが集まってゲームを準備できるようにすることを主な目的とするアプリケーションである。通常はリモート コンピュータにあり、インターネットを通じてアクセスする。ロビー サーバーは、チャット ルームのホスト、ニュースや情報の投稿、商品の販売などといったその他のさまざまな機能を実行することが多い。

マルチプレーヤー ゲームを管理するため、通常、ロビー サーバーは以下を含む多様な作業を行う。

  • 各種のゲーム セッションおよびプレーヤーのネットワーク アドレスを管理する。
  • プレーヤーのコンピュータにある関連するゲーム アプリケーションを起動して、セッションを開始する。
  • 進行中のセッションにプレーヤーを追加する。
  • セッション内の各種コンピュータを、正しいネットワーク アドレスに接続する。
  • プレーヤーがゲームを抜ける、ゲーム ホストが移行する、といったセッションの変化を把握する。

ロビー サーバー アプリケーションの詳細は、ベンダーが提供しようとしているサービスの種類によって異なる。Microsoft® DirectPlay® では、ロビー サーバーの実装方法も、ロビー サーバーとユーザー コンピュータの通信方法も、指定されていない。ただし、ロビー ベンダーは、DirectPlay 互換のロビー クライアントを実装し、ユーザーに配布しなければならない。


ロビー クライアント

ロビー クライアントとは、ロビー サーバーのベンダーが実装し、各プレーヤーのコンピュータにインストールされるアプリケーションである。ロビー クライアントは、プレーヤーおよびゲーム アプリケーションと、ロビー サーバーの間の通信を処理する。ロビー クライアントをインストールするには、通常、サインアップ手順の一部で、ユーザーにロビー サーバーの Web サイトからロビー クライアントをダウンロードさせる。

一般的なシナリオは次のようになる。

  1. 新しいプレーヤーが Web サイトにアクセスし、サインアップする。
  2. サインアップ手順の一部で、ロビー クライアントがクライアントのコンピュータにダウンロードされる。
  3. プレーヤーが、プレーするゲームを選び、セッションへの参加を要求する。
  4. Web サイトが、プレーヤーのコンピュータにあるロビー クライアントを起動する。通常の起動メカニズムは、ロビー クライアントの実行ファイルを指す URL である。
  5. ロビー クライアントが、手順を踏んでセッションを準備してから、ユーザーのゲーム アプリケーションを起動する。
  6. そのゲームがロビー可能アプリケーションなら、ロビー クライアントは、ゲーム アプリケーションがロビー サーバーと通信できるようにする。この接続により、ロビー サーバーは、プレーヤーがゲームに加わったりゲームから抜けたりする、ホストが移行する、といったイベントを把握できる。

ロビー クライアントは、リモート サーバーにリンクされていなくてもよい。ユーザーがロビー クライアントを直接起動する、という別のシナリオもある。この場合、ロビー クライアントが、(たとえばユーザーの LAN サブネットに接続されている) 利用可能なゲームとセッションを表示する。ユーザーがゲームとセッションを選ぶと、ロビー クライアントがゲームを起動する。

ここでは、ロビー クライアントが持ついくつかの一般的な機能について説明する。ロビー クライアントとそれに関連するロビー サーバーとの通信の詳細については、｢ロビー可能ゲームとの通信｣を参照すること。

実装の詳細については、｢ロビー クライアントの実装｣または SDK 付属のサンプル アプリケーション LobbyClient を参照すること。


ロビー可能ゲームとの通信

ロビー クライアントとそれに関連するロビー サーバーとの通信は、都合のよい方法で自由に処理できる。Microsoft® DirectPlay® では、ロビー クライアントがロビー可能ゲーム アプリケーションと通信する方法だけが指定されている。

ロビー クライアントは、ゲーム アプリケーションと直接通信しない。代わりに、DirectPlay8LobbyClient オブジェクトと通信する。ゲーム アプリケーションがロビー可能なら、この結果、ロビー対象アプリケーション オブジェクトがゲームにメッセージを渡す。ロビー クライアントは、DirectPlay8LobbyClient オブジェクトを使って以下のことを実行できる。

  • ユーザーのシステムにあるロビー可能アプリケーションを列挙する。
  • 既に実行中でなければアプリケーションを起動し、セッションに接続する。
  • アプリケーションをセッションから解放し、ロビー クライアントとのリンクを閉じる。
  • ロビー クライアントから起動または接続されたロビー対象アプリケーションに、メッセージを送信する。

注 DirectPlay ロビー クライアントは、ロビー可能かどうかにかかわらず、あらゆるアプリケーションを起動できる。ただし、ゲームの進行中に DirectPlay を使ってロビー クライアントに応答できるのは、ロビー可能アプリケーションだけである。

ロビー クライアント オブジェクトは、DirectPlay8LobbyEvent メッセージ ハンドラ オブジェクトを通じて、ロビー クライアントと通信する。DirectPlay8LobbyEvent オブジェクトは、本来、ロビー クライアント オブジェクトからは直接、アプリケーションからは間接的に、通知を受けるイベント ハンドラである。イベント ハンドラは、DirectPlay から提供されないので、アプリケーションで実装する必要がある。詳細については、リファレンス ドキュメントを参照すること。このオブジェクトは、DirectPlay8LobbyClient.RegisterMessageHandler を呼び出して DirectPlay に登録しなければならない。

ロビー クライアント オブジェクトは、DirectPlay8LobbyEvent オブジェクトを使って以下のような情報をロビー クライアントに送信できる。

  • 接続情報。
  • 接続の状態。
  • セッションの状態 (接続、切断、ホストの移行など)。
  • アプリケーションからロビー クライアントへのメッセージ。

アプリケーションの起動

アプリケーションには、起動時にゲーム固有のデータ ブロックを渡すことができる。ロビー クライアントからロビー可能アプリケーションが起動されると、アプリケーションはロビー対象アプリケーション オブジェクトを作成し、初期化する。情報は、この初期化メソッドを通じてゲームに渡される。

ロビー対象アプリケーション オブジェクトが初期化されると、ユーザーが接続されたことを示すメッセージがロビー クライアントに届く。このメッセージが持つ主な目的の 1 つは、アプリケーションがロビー可能であることをロビー クライアントに知らせることである。起動後にある程度の時間が経過しても、ロビー クライアントに接続メッセージが届かない場合には、ゲームがロビー可能でないので、この接続をあきらめることができる。

アプリケーションの起動後

ロビー可能ゲームが始まると、ロビー クライアントは比較的暇になる。ユーザーのメッセージの多くは、ゲーム トポロジに応じて、ほかのプレーヤーに直接送信されるか、またはゲーム サーバーに送信される。ただし、切断やホストの移行といったイベントが発生すると、DirectPlay からロビー クライアントにメッセージが送信される。これらのメッセージにより、ロビー クライアントがロビー サーバーに状態変化を渡すことが可能になる。たとえば、ホストが移行した場合、ロビー サーバーは UI に新しいホストを反映できる。

アプリケーションは、ロビー クライアントにメッセージを渡すこともできる。このメッセージには事実上あらゆるデータを格納できる。また、用途にも制限はない。ロビー クライアントは、通常、そのデータをロビー サーバーに渡して処理を任せる。たとえば、ゲームの終了時に、ロビー サーバーのハイスコア一覧を更新するため、アプリケーションからロビー サーバーにメッセージを送信してもよい。


ロビー可能アプリケーション

ロビー可能アプリケーションは、Microsoft® DirectPlay® ベースのロビー クライアントと連動するようになっている。ロビー クライアントは DirectPlay を使って任意のアプリケーションを起動できるが、ロビー可能アプリケーションには多くの利点がある。

  • ゲームの状態が変化すると、ロビー クライアントに対して最新状態が自動的に送られる。
  • ロビー クライアントは、標準 API を使ってアプリケーションと通信できる。
  • アプリケーションは、標準 API を使ってロビー クライアントと通信できる。

要するに、DirectPlay を使用すれば、ゲーム固有またはロビー クライアント固有の通信コードはほとんど必要ない。特定のゲームやロビー クライアントのための修正をほとんど (またはまったく) 行わずに、何にでも標準 API を使用できる。

ここでは、ロビー可能アプリケーションが持ついくつかの一般的な機能について説明する。詳細については、｢ロビー可能アプリケーションの起動｣を参照すること。

実装の詳細については、｢ロビー可能アプリケーションの実装｣または SDK のサンプル (SimplePeer、StagedPeer など) を参照すること。


ロビー可能アプリケーションの起動

起動された後にロビー可能アプリケーションが実行すべき作業の 1 つは、DirectPlay8LobbiedApplication オブジェクトを作成することである。このオブジェクトの最も重要な機能は、アプリケーションがロビー起動で起動されているかどうかを判断することにある。また、ロビー対象アプリケーションは、ロビー クライアントからメッセージを受信するために、メッセージ ハンドラ コールバック関数を実装する必要もある。基本的な手順は以下のとおりである。

  • DirectPlay8LobbiedApplication オブジェクトを作成する。
  • DirectPlay8LobbiedApplication.RegisterMessageHandler を呼び出して、DirectPlay8LobbyEvent メッセージ ハンドラ オブジェクトを登録する。
  • アプリケーションがロビー起動で起動されている場合は、DirectPlay から DirectPlay8LobbyEvent.Connect メソッドが呼び出される。dlNotify パラメータには、セッション メンバのアドレス オブジェクトといった接続情報が付いた DPL_MESSAGE_CONNECT 型が格納される。

注 DirectPlay8LobbyEvent オブジェクトは、基本的には、ロビー対象アプリケーションからは直接、ロビー クライアントとロビーからは間接的に、通知を受けるイベント ハンドラである。イベント ハンドラは、DirectPlay から提供されないので、アプリケーションで実装する必要がある。詳細については、リファレンス ドキュメントを参照すること。

アプリケーションのロビー起動が成功すると、ホストの移行などのイベントが発生したときに、Microsoft® DirectPlay® からロビー クライアントに対して最新状態が自動的に送信されるようになる。また、ロビー対象アプリケーションのインターフェイスを使って、ロビー クライアントにメッセージを送信することもできる。

メッセージ ハンドラ オブジェクトは、初期化メソッドから復帰する前に、ロビー クライアントから呼び出されることがあるので、注意が必要である。接続メッセージに加えて、ロビー クライアントが接続の設定を変更したか、または接続を切断したときにも、DirectPlay はこのオブジェクトを呼び出す。また、ゲーム固有の情報が入ったメッセージを、ロビー クライアントからメッセージ ハンドラに直接送信することもできる。


ネットワーキングの基本

ここでは、Microsoft® DirectPlay® アプリケーションを作成するために理解しなければならないネットワーキング技術について、基本的な事項をいくつか説明する。ネットワーキング技術の一般的な説明については、この分野に関する標準的な文献 (Andrew Tannenbaum 著の『Computer Networks』など) を参照すること。デフォルトの DirectPlay8 TCP/IP ダイアログをオーバーライドしようとするアプリケーション開発者は、接続や列挙に使用するポートをユーザーにオーバーライドさせるソリューションをかならず実装すべきである。1 つの可能なソリューションはデフォルトの DIrectPlay8 TCP/IP ダイアログが実装しているように (つまり "host.domain.com:8090" のように)、ユーザーにコロンでホスト名にポートを追加させる方法である。もう 1 つの可能なソリューションはユーザーがポートを入力できる別の UI フィールドを追加することである。

  • DirectPlay サービス プロバイダ
  • DirectPlay アドレシング
  • DirectPlay プロトコル
  • ネットワーク使用量の最適化
  • アプリケーションにおける DirectX プロトコルの使い方


DirectPlay サービス プロバイダ

Microsoft® DirectPlay® は、アプリケーションに仮想のネットワーク接続を提供する。この仮想ネットワーク接続を使用すると、関係するネットワークの種類にかかわらず共通の方法で、ほかのコンピュータと通信することができる。このレベルの抽象化を実現するため、ネットワーク接続はサービス プロバイダを通じて行われる。サービス プロバイダを選択すると、アプリケーションが、DirectPlay の適切なメソッドを使って、セッション内のほかのコンピュータと通信するようになる。選択したネットワーク ハードウェアをとおる通信の詳細は、そのサービス プロバイダで処理される。

DirectPlay には、TCP/IP、IPX、モデム、およびシリアルの 4 種類のネットワーク接続に対応するサービス プロバイダが含まれている。サービス プロバイダの選択方法については、「DirectPlay アドレシング」を参照すること。

注 Microsoft Windows® 95 システムでモデムを使用するには、TAPI (テレフォニー API) のバージョン 2.0 をインストールする必要がある。TAPI 2.0 は、http://www.microsoft.com/ からダウンロードできる。


DirectPlay アドレシング

メッセージを配信するには、マルチプレーヤー ゲームの各参加者が一意のアドレスを持っている必要がある。アドレスは、アプリケーションを実行しているコンピュータを参照するか (デバイス アドレス)、アプリケーションが通信する必要のあるコンピュータを参照できる (ホスト アドレス)。デフォルトの DirectPlay8 TCP/IP ダイアログをオーバーライドしようとするアプリケーション開発者は、接続や列挙に使用するポートをユーザーにオーバーライドさせるソリューションをかならず実装すべきである。1 つの可能なソリューションはデフォルトの DIrectPlay8 TCP/IP ダイアログが実装しているように (つまり "host.domain.com:8090" のように)、ユーザーにコロンでホスト名にポートを追加させる方法である。もう 1 つの可能なソリューションはユーザーがポートを入力できる別の UI フィールドを追加することである。

Microsoft® DirectPlay® 8.0 では、アドレスを URL 文字列の形で表現する。このアドレス文字列は、さらに、DirectPlay8Peer.Connect などのメソッドの入出力パラメータとして渡される DirectPlay8Address アドレス オブジェクト内にカプセル化される。

ここでは、DirectPlay アドレスの 2 つ処理方法について説明する。

  • 「DirectPlay URL」は、アドレス文字列を直接構築する方法である。
  • 「DirectPlay アドレス オブジェクト」は、アドレス オブジェクトの IDirectPlay8Address インターフェイスで公開されるメソッドを使って、アドレス文字列を操作する方法である。


DirectPlay URL

Microsoft® DirectPlay® では、アドレスを URL として表現する。一般に、URL は、スキーム、スキーム セパレータ、およびデータ文字列の 3 つの基本要素が、この順序に並べられた文字列である。

すべての DirectPlay アドレスは、スキームとして "x-directplay" を使用し、スキームのセパレータとして ":/" (コロンとそれに続く順スラッシュ) を使用する。セパレータとして ":/" を使用すると、後に続くデータが不透明であることを示す。言い換えると、データ文字列はどのインターネット標準にも適合しておらず、受け取り側アプリケーションにそのまま渡す必要がある。したがって、DirectPlay のすべての URL は次の一般形式になる。

x-directplay:/[data string]

注 スキームのセパレータとして "://" (コロンとそれに続く 2 つの順スラッシュ) を使用しないこと。このセパレータは、後続のデータがインターネット標準に適合しており、その標準に従って解釈できることを示す。混乱を避けるため、DirectPlay では、"://" を含むすべての URL が無効と見なされる。

説明するトピックは、次のとおりである。

  • データ文字列
  • データ値
  • データ値の概要
  • サンプル URL


データ文字列

データ文字列には、アドレス情報が保持される。データ文字列の最初の部分は、セミコロン (;) で区切られた一連の要素 "keyname=value" から成り立っている。最後の値の後にシャープ記号 (#) を付け、アプリケーションで定義した文字列を続けると、オプションのユーザー データを含めることができる。

キー名は、データを識別し、値に入っているデータの種類を非明示的に示す小文字の文字列である。たとえば、"provider" というキー名は、Microsoft® DirectPlay® サービス プロバイダの GUID が、GUID 文字列の形で値に格納されていることを示す。以下の文字は予約済みなので、値の文字列に使用しないこと。

アンパサンド (&) | 順スラッシュ (/)
アット マーク (@) | シャープ記号 (#)
コロン (:) | 疑問符 (?)
等号 (=) | セミコロン (;)

データ文字列の最初の要素は、プロバイダでなければならない。ほかの要素は、任意の順序で続けることができる。一般的な URL は、次のようになる。

x-directplay:/provider=%provider GUID%;[keyname1=value1];[keyname2=value2][...]#[user defined string]


データ値

データ文字列に含まれていなければならない値は、サービス プロバイダによって異なる。たとえば、モデム プロバイダのアドレスには電話番号が必要だが、LAN プロバイダではポート番号が必要かもしれない。ここでは、標準のデータ値について詳しく説明する。また、文字列そのものの代わりに使用できるキー名についても触れる。Dpaddr.h には、以下の名前が定義されている。

  • Application Instance
  • Baud
  • Device
  • Flow Control
  • Host Name
  • Parity
  • Phone Number
  • Port
  • Program
  • Provider
  • Stop Bits

Application Instance

アプリケーション インスタンスを識別するオプションの GUID。接続先のゲームを指定するときには、この値が使用される。

キー名 : DPNA_KEY_APPLICATION_INSTANCE

キー文字列 : "applicationinstance"

データ型 : GUID

プロバイダ : すべて。

有効な値 : 任意の有効なアプリケーション インスタンス GUID。

Baud

ボー レート。

キー名 : DPNA_KEY_BAUD

キー文字列 : "baud"

データ型 : DWORD

プロバイダ : モデムおよびシリアル。

有効な値 :任意の有効なボー レート。この値には、適切な整数を設定してもよいし、Dpaddr.h にあらかじめ定義されている以下の値のいずれかを使用してもよい。

DPNA_BAUD_RATE_9600
DPNA_BAUD_RATE_14400
DPNA_BAUD_RATE_19200
DPNA_BAUD_RATE_38400
DPNA_BAUD_RATE_56000

Device

ローカル コンピュータ上で使用するデバイスを識別する GUID。サービス プロバイダがすべてのアダプタをサポートしていれば、デバイスを指定する必要はない。

キー名 : DPNA_KEY_DEVICE

キー文字列 : "device"

データ型 : GUID

プロバイダ : すべて。ただしデバイス アドレス専用。ホスト アドレスは除く。

有効な値 : 任意の有効なデバイス GUID。

Flow Control

使用するフロー制御の種類。

キー名 : DPNA_KEY_FLOWCONTROL

キー文字列 : "flowcontrol"

データ型 : String

プロバイダ : シリアルおよびモデム。

有効な値 : Dpaddr.h にあらかじめ定義されている以下の値のいずれか。

DPNA_FLOW_CONTROL_NONE | DPNA_FLOW_CONTROL_DTR
DPNA_FLOW_CONTROL_XONXOFF | DPNA_FLOW_CONTROL_RTSDTR
DPNA_FLOW_CONTROL_RTS |

Host Name

リモート ホスト コンピュータの名前。

キー名 : DPNA_KEY_HOSTNAME

キー文字列 : "hostname"

データ型 : String

プロバイダ : すべて。ただしホスト アドレス専用。デバイス アドレスは除く。

有効な値 : 完全に修飾されたホスト名か、またはドットが含まれるアドレス。

Parity

接続のパリティ。

キー名 : DPNA_KEY_PARITY

キー文字列 : "parity"

データ型 : String

プロバイダ : シリアルおよびモデム。

有効な値 : Dpaddr.h にあらかじめ定義されている以下の値のいずれか。

DPNA_PARITY_NONE | DPNA_PARITY_MARK
DPNA_PARITY_EVEN | DPNA_PARITY_SPACE
DPNA_PARITY_ODD |

Phone Number

電話番号。

キー名 : DPNA_KEY_PHONENUMBER

キー文字列 : "phonenumber"

データ型 : String

プロバイダ : モデム。

有効な値 : 任意の有効な電話番号。

Port

オプションのポート番号。

キー名 : DPNA_KEY_PORT

キー文字列 : "port"

データ型 : DWORD

プロバイダ : IP および IPX。

有効な値 : 任意の 16 ビット整数。値の下位 16 ビットのみが意味を持つ。ポートを指定しなかった場合は、自動的に選択される。

Program

オプションのアプリケーション GUID。

キー名 : DPNA_KEY_PROGRAM

キー文字列 : "program"

データ型 : GUID

プロバイダ : すべて。

有効な値 : 任意の有効なアプリケーション GUID。

Provider

使用する Microsoft® DirectPlay® サービス プロバイダを識別する GUID。

キー名 : DPNA_KEY_PROVIDER

キー文字列 : "provider"

データ型 : GUID

プロバイダ : すべて。

有効な値 : 任意の有効なサービス プロバイダ GUID。

Stop Bits

ストップ ビット数。

キー名 : DPNA_KEY_STOPBITS

キー文字列 : "stopbits"

データ型 : String

プロバイダ : シリアルおよびモデム。

有効な値 : Dpaddr.h にあらかじめ定義されている以下の値のいずれか。

DPNA_STOP_BITS_ONE | DPNA_STOP_BITS_TWO
DPNA_STOP_BITS_ONE_FIVE |


データ値の概要

以下の 2 つの表は、標準のデータ値の概要であり、各タイプのサービス プロバイダがホスト アドレスとデバイス アドレスの両方に使用する値を示している。

ホスト アドレス

 | IP | IPX | シリアル | モデム
Application Instance | 省略可能 | 省略可能 | 省略可能 | 省略可能
Baud | 未使用 | 未使用 | 必須 |
Device | 未使用 | 省略可能 | 必須 | 必須
Flow Control | 未使用 | 未使用 | 必須 |
Host Name | 必須 | 必須 | 省略可能 | 省略可能
Parity | 未使用 | 未使用 | 必須 |
Phone Number | 未使用 | 未使用 | 未使用 | 必須
Port | 必須 | 必須 | 未使用 | 未使用
Program | 省略可能 | 省略可能 | 省略可能 | 省略可能
Provider | 必須 | 必須 | 必須 | 必須
Stop Bits | 未使用 | 未使用 | 必須 |

デバイス アドレス

 | IP | IPX | シリアル | モデム
Application Instance | 省略可能 | 省略可能 | 省略可能 | 省略可能
Baud | 未使用 | 未使用 | 必須 | 未使用
Flow Control | 未使用 | 未使用 | 必須 | 未使用
Host Name | 省略可能 | 省略可能 | 省略可能 | 省略可能
Device | 省略可能 | 必須 | 必須 | 必須
Parity | 未使用 | 未使用 | 必須 | 未使用
Phone Number | 未使用 | 未使用 | 未使用 | 未使用
Port | 省略可能 | 必須 | 未使用 | 未使用
Program | 省略可能 | 省略可能 | 省略可能 | 省略可能
Provider | 必須 | 必須 | 必須 | 必須
Stop Bits | 未使用 | 未使用 | 必須 | 未使用


サンプル URL

以下のサンプル URL は、4 つの標準サービス プロバイダに対応する Microsoft® DirectPlay® URLの例を示している。

ローカル IP アドレス

x-directplay:/provider=%7BEBFE7BA0-628D-11D2-AE0F-006097B01411%7D;device=%7BIP ADAPTER GUID%7D;port=0000230034#IPUserData

ローカル IPX アドレス

x-directplay:/provider=%7B53934290-628D-11D2-AE0F-006097B01411%7D;device=%7BIPX ADAPTER GUID%7D;port=00230#IPXUserData

ローカル シリアル アドレス

x-directplay:/provider=%7B743B5D60-628D-11D2-AE0F-006097B01411%7D;device=%7BCOM PORT GUID%7D;baud=57600;stopbits=1;parity=NONE;flowcontrol=RTSDTR#SerialUserData

リモート モデム アドレス

x-directplay:/provider=%7B6D4A3650-628D-11D2-AE0F-006097B01411%7D;device=%7BMODEM DEVICE GUID%7D;phonenumber=555-1212#ModemUserData


アドレスの処理

IDirectPlay8Peer、IDirectPlay8Client、または IDirectPlay8Server で公開される Host、EnumHosts、または Connect メソッドを呼び出す場合は、アドレス オブジェクトをパラメータとして渡す必要がある。Microsoft® DirectPlay® に十分なアドレス情報がないと、呼び出したメソッドが失敗し、DPNERR_ADDRESSING が返される。ただし、メソッドを呼び出すときに、アドレス オブジェクト内の情報がすべて揃っている必要はない。

すべてのアドレス オブジェクトには、サービス プロバイダ GUID が設定されている必要があるが、その他のデータ値は省略可能である。

  • サービス プロバイダがすべてのアダプタをサポートしていれば、デバイスを省略できる。
  • IP および IPX サービス プロバイダでは、Host、EnumHosts、および Connect メソッドのポート番号を省略できる。ポート番号は、DirectPlay で割り当てられる。この番号は状況によって異なる。
  • OKTOQUERYFORADDRESSING フラグを設定すると、アドレスに足りない情報をユーザーにたずねるダイアログ ボックスを、サービス プロバイダが表示できる。ユーザーが十分な情報を提供しなければ、メソッドは失敗する。OKTOQUERYFORADDRESSING フラグを設定しなかった場合、このダイアログ ボックスは表示されない。メソッドに渡したアドレスが足りなければ、メソッドは失敗する。最後の 2 つの場合、返されるエラー値は DPNERR_ADDRESSING となる。

IP および IPX サービス プロバイダに関しては、重要な注意事項が 2 つある。これらの処理が適切でないと、アプリケーションが失敗する可能性がある。

  • 列挙メソッドを呼び出すときに NOBROADCASTFALLBACK フラグを設定する場合は、ホスト名を渡す必要がある。そうしないと、メソッドが失敗し、DPNERR_ADDRESSING が返される。
  • ポートを指定しない場合、DirectPlay により常に同じポート番号が選択されると考えてはならない。特定のポート番号を使用する唯一の方法は、アドレスでそのポート番号を指定することである。ポート番号を指定しない場合は、後でコマンドの進行中に実際の値を取得する必要がある。

デフォルトの DirectPlay8 TCP/IP ダイアログをオーバーライドしようとするアプリケーション開発者は、接続や列挙に使用するポートをユーザーにオーバーライドさせるソリューションをかならず実装すべきである。1 つの可能なソリューションはデフォルトの DIrectPlay8 TCP/IP ダイアログが実装しているように (つまり "host.domain.com:8090" のように)、ユーザーにコロンでホスト名にポートを追加させる方法である。もう 1 つの可能なソリューションはユーザーがポートを入力できる別の UI フィールドを追加することである。


DirectPlay アドレス オブジェクト

Microsoft® DirectPlay® では、URL 文字列を直接処理しない。代わりに、文字列を DirectPlay8Address オブジェクト内にカプセル化する必要がある。このオブジェクトは、多くのメソッドを公開する。これらのメソッドを使用すると、アドレス オブジェクトに URL 情報を挿入したり、逆にアドレス オブジェクトから URL 情報を抽出したりできる。

DirectPlay アドレスを作成するには、最初に DirectPlay8Address オブジェクトを作成する必要がある。この結果、以下の 2 つの方法のどちらかでアドレスを定義できるようになる。

  • URL 文字列を直接作成する。次に、作成した文字列を DirectPlay8Address.BuildFromURL を使って挿入する。
  • ほかの DirectPlay8Address メソッドを使って、文字列を構成する各種のデータをオブジェクトに直接挿入する。

アドレス オブジェクトを受け取るときにも、同様の 2 つの選択肢がある。

  • DirectPlay8Address.GetURL を使って、URL 文字列全体を抽出する。次に、その文字列を解析して必要な情報を抽出する。
  • ほかの DirectPlay8Address メソッドを使って、興味のある特定のデータをアドレス オブジェクトから抽出する。


DirectPlay プロトコル

マルチプレーヤー ゲームには、最高のパフォーマンスを提供するために、効率的で柔軟なネットワーク メッセージング サービスが必要になる。Microsoft® DirectPlay® プロトコルは、すべての DirectPlay メッセージングに使用される、トランスポート レイヤのメッセージング プロトコルである。DirectPlay 8.0 では、このプロトコルが大幅に改訂されている。新しいプロトコルは、アプリケーションがあらゆる面で円滑に動作するために必要なメッセージング サポートを提供する。DirectPlay プロトコルには、以下のメッセージング サポートが含まれる。

  • 高信頼性および低信頼性のメッセージ配信
  • シーケンシャル メッセージ配信と非シーケンシャル メッセージ配信
  • メッセージの分割と再構成
  • 混雑の制御
  • 送信の優先順位付け
  • メッセージのタイムアウト

注 DirectPlay の以前のバージョンでは、DirectPlay プロトコルはオプションであり、明示的に指定しなければらならなかった。DirectPlay 8.0 では、DirectPlay のすべてのメッセージングにこのプロトコルが使用される。

このドキュメントでは、DirectX の動作の様子、およびアプリケーションにおけるDirectX の使い方について、概要を説明する。

  • メッセージ処理の基本
  • メッセージのカテゴリ
  • 混雑の制御
  • 送信の優先順位付け
  • メッセージング統計情報の監視
  • 未処理メッセージ キューの監視


メッセージ処理の基本

メッセージという用語は、このドキュメントで使用される場合、別のコンピュータに送信する必要があるデータ ブロックを意味する。ネットワーク プロトコルは、データ ブロックにターゲットのネットワーク アドレスといった情報を保持するいくつかのビットを追加して、"パケット" を作成する。このパケットが、ネットワーク データの基本単位となる。パケットがターゲットに届くと、ターゲットのネットワーク プロトコルが、余分のビットを削除し、受け側のアプリケーションにそのデータ ブロックを渡す。

使い方は似ているが、"メッセージ" という用語と "パケット" という用語は厳密には互換でない。このドキュメントでは、Microsoft® DirectPlay® API とやり取りする情報の単位を、"メッセージ" と表現する。また、ネットワークが処理する情報の単位を、"パケット" と表現する。パケットは、DirectPlay 内部で処理される。ごく稀な例外を除き、DirectPlay アプリケーションではメッセージだけを処理すればよい。

"メッセージ" と "パケット" を区別する主な理由は、ネットワークで処理されるパケットの最大サイズが通常制限されていることにある。このサイズを、最大伝送単位 (MTU) という。メッセージが小さい場合は、メッセージが単独パケットで送信されるため、2 つの用語は事実上同義である。一方、大きいメッセージは、複数のパケットに分割して送信し、受け側で再構成しなければならないことがある。DirectPlay プロトコルでは、メッセージの分割および再構成が必要に応じて自動的に処理される。どちらの場合も、アプリケーションに関する限り、メッセージを送信し、ターゲットがそれを受け取るということは変わらない。

注 DirectPlay が配信するメッセージのサイズに制限はない。ただし、単独メッセージに必要なパケット数が増えるほど、パケットが失われ、再送信しなければならない確率が高くなる。したがって、分割および再構成が必要な大きいメッセージでは、通常、単独パケットのメッセージよりネットワークの遅延時間が大きくなる。ネットワークの遅延時間を最小限に抑える必要がある場合は、(ネットワークの損失が多い場合には特に) 大きなメッセージの送信を避けること。現在の接続で単独パケットに収容できる最大のメッセージ サイズは、DirectPlay8Peer、DirectPlay8Client、および DirectPlay8Server インターフェイスで公開される GetSPCaps メソッドを呼び出して判断できる。


メッセージのカテゴリ

Microsoft® DirectPlay® プロトコルは、以下の 2 種類の基本的なネットワーク メッセージングを処理するようになっている。

  • "高信頼性" 対 "低信頼性"。ターゲット アプリケーションにメッセージが確実に配信されることを保証するかどうかが異なる。
  • "シーケンシャル" 対 "非シーケンシャル"。送信されたときと同じ順序で、メッセージがターゲットに届くかどうかが異なる。

ゲームでは、さまざまな目的でメッセージングが使用され、個々の要求も多様である。メッセージングへのこの広範な要求に対応するため、DirectPlay プロトコルでは、メッセージを以下の 4 つのカテゴリに分類できる。

  • 高信頼性でシーケンシャル
  • 低信頼性でシーケンシャル
  • 高信頼性で非シーケンシャル
  • 低信頼性で非シーケンシャル

DirectPlay プロトコルでは、メッセージごとにカテゴリを割り当てて、メッセージング方法を最適化することができる。

高信頼性メッセージングと低信頼性メッセージング

メッセージは伝送の過程で失われることがある。"高信頼性" メッセージングでは、すべてのメッセージがターゲットに届くことが保証される。データの損失が許されないときは、この種類のメッセージングが必要になる。"高信頼性" メッセージングの多くのスキームでは、ターゲットに対して各メッセージの受信確認を求める。指定されたタイムアウト時間内に受信確認が届かない場合、差出人はメッセージを再送信する。通常、メッセージが届いたことを示す受信確認を差出人が受け取るまで、この手順が繰り返される。

DirectPlay プロトコルでは、再送信の回数に上限が設定されている。再送信をある程度繰り返しても受信確認が届かない場合、DirectPlay は接続が失われたものと見なし、接続を閉じる。

低信頼性メッセージングは、最も簡単な形のネットワーク通信である。メッセージがターゲットに配信されることを保証しないため、高信頼性メッセージングより高速で通信できる。差出人がメッセージを送信する。ターゲットにメッセージが届かない場合、差出人はメッセージを再送信せず、パケットは失われる。

低信頼性メッセージングは、主に、メッセージが失われないことより速度または帯域幅を優先する場合に使用される。たとえば、高帯域幅のストリーミング メディア アプリケーションでは、低信頼性メッセージングを採用することが多い。これらのアプリケーションでは、帯域幅を受信確認や再送信に充てる余裕がなく、失われたメッセージの再送信を待つこともできない。メッセージがときどき失われることは、品質にほとんど影響しないことが多く、無視しても問題ない。

シーケンシャル メッセージングと非シーケンシャル メッセージング

メッセージは特定の順序で差出人の手を離れる。ただし、送信されたときと同じ順序でメッセージがターゲットのコンピュータに届くという保証はない。たとえば、メッセージが失われて再送信が必要になった場合、通常、そのメッセージは元の順序で後ろにあったメッセージより後に届く。

シーケンシャル メッセージングでは、メッセージに埋め込まれた順序情報を使って、メッセージが正しい順序でターゲット アプリケーションに渡される。ターゲット アプリケーションがメッセージを正しい順序で受信しなければならないときには、この種類のメッセージングが必要になる。順序どおりでないメッセージは、欠けているメッセージが届くまでバッファリングされる。

非シーケンシャル メッセージングでは、メッセージが、送信された順序に関係なく、ターゲット コンピュータに届くと同時にターゲットに渡される。非シーケンシャル メッセージングは、欠けているパケットを待つ必要がないので、メッセージが順序どおりに届くことより速度を優先する場合に使用されることが多い。順序どおりでないメッセージは無視される。

最適なメッセージ カテゴリの選択

メッセージに適したカテゴリの選択は、マルチプレーヤー ゲームを開発するうえで中心になる問題である。DirectPlay にはメッセージングを管理するためのツールが用意されているが、メッセージ カテゴリの選択は、最終的にはメッセージの意味とゲームの性質に依存する。

最適なメッセージ カテゴリを選択するための一般的なガイドラインは、以下のようになる。

  • 内容的に問題がなければ、非保証のメッセージングを使用する。たとえば、プレーヤーの最新位置を頻繁に送信する場合を考える。更新内容は互いに無関係であり、新しい情報は以前の情報すべてに取って代わる。更新内容が失われても、次回の更新でプレーヤーのゲームの状態を維持できる。メッセージが失われ、再送信されると、後続の更新メッセージより後に届く可能性がある。
  • データの損失が許されないときには、保証のあるメッセージングを使用する。たとえば、テキストベースのチャット機能では、すべての文字をそのターゲットに配信する必要がある。
  • メッセージの順序が重要なときには、シーケンシャル メッセージングを使用する。たとえば、ストリーミング メディア アプリケーションでは、通常、シーケンシャルの低信頼性メッセージングを採用する。メッセージがときどき失われることは許されるが、メッセージが順序どおりに届かないと問題が起きる可能性がある。


混雑の制御

理想的な環境では、メッセージを必要なだけ送信できる。メッセージは直ちにターゲットへ届き、即座に処理される。ゲームにかかわるすべてのコンピュータが、十分な処理能力を持ち、負荷の軽い高帯域幅のネットワーク リンクで接続されていれば、この理想的環境に近付くことができる。そのうえで、メッセージを必要なだけ送信できる。ただし、多くの要因によって "混雑" が発生し、メッセージングが理想より遅くなることがある。

  • ネットワークの遅延時間。理想的な状況でも、メッセージがネットワークを通じて差出人からターゲットに渡るには、ある程度の時間がかかる (インターネットを通る場合は特に)。受信確認、失われたパケットの再送信、または順序どおりでないパケットの再構成が行われると、この時間はさらに長くなる。
  • ネットワークの帯域幅。コンピュータがメッセージを送受信できる速度は、ネットワークの帯域幅によって制御される。ネットワーク リンクの帯域幅の範囲は広い。また、高帯域幅のネットワークであっても、トラフィックの水準が高ければ速度が落ちる可能性がある。低帯域幅の接続を使用しているプレーヤーがいる場合、それらのプレーヤーは、限られた速度でしかメッセージを送受信できない。
  • 処理速度。ネットワークの帯域幅が高く、遅延時間が少なくても、受信したメッセージをターゲット アプリケーションが処理するには、ある程度の時間がかかる。セッション内に比較的低速のコンピュータを使用しているプレーヤーがいる場合、これらのプレーヤーが受信したメッセージを処理できる速度は、メッセージの送信速度より低くなる可能性がある。

メッセージのスロットリング

メッセージの送信速度を制御しないと、大量のメッセージがターゲットに届き、処理しきれない可能性がある。この状況を避けるため、Microsoft® DirectPlay® プロトコルでは、メッセージの送信速度を "スロットリング" する。スロットリングの最終的な効果は、ターゲットがメッセージを処理できる速度によって、メッセージが送信される速度が制御されることである。

スロットリングは、"スライディング ウィンドウ" メカニズムを使って実装される。スライディング ウィンドウは、基本的には限られた数のスロットを持つキューであり、受信されていない送信済みのメッセージを保持する。流出するメッセージは、メッセージのカテゴリに関係なく、すべてこのキューに入れられる。送信済みメッセージ キューが一杯になると、キュー内のメッセージのいずれかが受信されるまで、流出するメッセージが受け付けられなくなる。

最高のパフォーマンスを提供するためには、スライディング ウィンドウのサイズを現在のネットワーク状況に合わせる必要がある。DirectPlay プロトコルでは、送信済みメッセージ キュー内のメッセージ数や総バイト数などの要素が、自動的に監視される。次に、現在のネットワーク状況に合わせてメッセージングを最適化するため、この情報を使ってスライディング ウィンドウのサイズが動的に調整される。

接続の検査

リンクが利用されていないと、DirectPlay プロトコルでは、高信頼性の空パケットを送信して繰り返し接続をテストする。再送信をある程度繰り返してもターゲットから受信確認が届かない場合、DirectPlay は接続が切断されたものと見なす。


送信の優先順位付け

メッセージの重要性は、メッセージごとに異なる。あるメッセージはタイム クリティカルで、できる限り速く配信しなければならない。また、あるメッセージは、必要に応じて遅らせることができるし、送信さえしないでよいかもしれない。混雑の制御アルゴリズムの 1 つの問題は、アプリケーションがメッセージを作成する速度が、送信可能な速度を上回る場合である。このような場合には、流出用のスロットが開くまで、未送信のメッセージをキューに保存する必要がある。未送信のメッセージをすべて単独の未処理メッセージ キューに保持すると、優先度の低いメッセージが先に送信されるまで、優先度の高いメッセージがブロックされる可能性がある。

Microsoft® DirectPlay® プロトコルでは、3 つの未処理メッセージ キュー (低優先度、中優先度、および高優先度) を用意することによって、この問題を解決する。送信済みメッセージ キューのスロットが開くと、次に送信すべきメッセージが次のように選択される。

  1. 高優先度キュー内で最も古いメッセージを送信する。
  2. 高優先度キューにメッセージがない場合は、中優先度キュー内で最も古いメッセージを送信する。
  3. 中優先度キューにメッセージがない場合は、低優先度キュー内で最も古いメッセージを送信する。

この優先度メカニズムにより、ほかのあまり重要でないメッセージが既に発行されていても、タイム クリティカルなメッセージをできる限り速く処理することができる。

送信のタイムアウト

スロットリングの 1 つの結果として、メッセージが未処理メッセージ キュー内に比較的長時間留まることがある (優先度が低い場合は特に)。場合によっては、メッセージが長時間保持されているうちに、そのメッセージに取って代わる後続メッセージが届くことがある。これらのメッセージは、もう不要である。たとえば、プレーヤーの最新位置を示すメッセージを周期的に送信する場合を考える。更新内容は互いに無関係であり、最新の情報は以前の情報すべてに取って代わる。未処理メッセージ キュー内にプレーヤーの最新位置が 2 つある場合、送信する必要があるのは最も新しいものだけである。

DirectPlay プロトコルでは、省略可能のタイムアウト値をメッセージに追加することで、古いメッセージの問題に対応できる。タイムアウト時間が過ぎたときに、まだ未処理メッセージ キューに保持されていると、そのメッセージは取り消される。

切断

アプリケーションが切断メッセージを送信すると、そのメッセージが低優先度の未処理メッセージ キューの最後に追加され、プロトコルが流出するメッセージの受け付けを停止する。この処理により、すべての未処理メッセージがリンク切断前に送信される。切断メッセージは、高信頼性のシーケンシャル メッセージとして送信され、ターゲットに届くことが保証されているが、その前にキュー内にあるほかのメッセージがすべて配信される。


メッセージング統計情報の監視

メッセージングの要素の多くは Microsoft® DirectPlay® プロトコルで自動的に処理されるが、メッセージングの動作はアプリケーションで監視しなければならない。たとえば、常時送信するメッセージの量に配信速度が追いつかないようであれば、メッセージング スキームを修正する必要があるかもしれない。

ネットワーク状況は常に変化しているので、ネットワーク動作の監視、およびその結果に応じたメッセージング スキームの調整は、定期的に行わなければならない。これには、メッセージングをサポートするすべての DirectPlay 8.0 オブジェクトで公開される GetConnectionInfo メソッドを呼び出す。GetConnectionInfo は、以下を含む各種の統計情報が入った型を返す。この統計情報を使ってメッセージング スキームを微調整することができる。

  • 往復時間
  • スループット
  • 送信パケット数
  • 受信パケット数
  • 再送信パケット数
  • 遺失パケット数
  • 転送メッセージ数 (優先度別)

注 メッセージング統計情報を取得するには、実際のネットワーク トラフィックを監視する。接続を初期化した直後に GetConnectionInfo を呼び出すと、データが短時間しか収集されないため、統計情報が参考にならないことがある。


未処理メッセージ キューの監視

未処理メッセージ キューは、大きくなりすぎないように監視しなければならない。DirectPlay8Peer、DirectPlay8Client、および DirectPlay8Server オブジェクトは、すべて GetSendQueueInfo メソッドを公開する。このメソッドを使用すると、キュー内の現在のメッセージ数とバイト数を確認できる。デフォルトでは 3 つのキューの合計が返されるが、3 つの優先度それぞれの値を取得することもできる。


ネットワーク使用量の最適化

快適なゲーム体験の提供とは、通常、最新情報やその他の情報を、ターゲットの処理能力を超えない範囲で、できる限り速く送信することを意味する。Microsoft® DirectPlay® プロトコルと非同期メッセージングを組み合わせると、メッセージング方法を動的に最適化して、ユーザーに快適なゲーム体験を提供することができる。

メッセージングの大半では、DirectPlay8Peer.SendTo、DirectPlay8Client.Send、または DirectPlay8Server.SendTo メソッドを使用する。これらのメソッドは、通常、メッセージ カテゴリに関係なく非同期に動作する。メソッドからは即座に復帰し、メッセージが実際に送信されると、DirectPlay からメッセージ ハンドラの DirectPlay8Event.SendComplete メソッドが呼び出される。

一方、DPNSEND_SYNC フラグを設定すれば、メッセージを同期で送信できる。その場合、Send および SendTo メソッドはメッセージが実際に送信されるまでブロックする。

DirectPlay プロトコルのスロットリング メカニズムでは、クライアントの処理能力を超える速度でメッセージが渡されないことが保証される。ただし、流出用のキューにメッセージが入る頻度は制御されない。このため、未送信メッセージのキューに大量のメッセージが溜まってしまうことがある。この状況はメッセージの送信頻度を抑えることによって避けることができるが、こうするとユーザーに提供されるゲーム体験の品質が不必要に低下しかねない。最もよいメッセージング方法は、ターゲットの処理能力を超えない範囲で、メッセージをできる限り速く送信することである。

メッセージング方法を最適化するためのヒントは、以下のようになる。

  • メッセージはできる限り非同期で送信する。メッセージを同期で送信すると、スロットリング メカニズムがメッセージの送信を許すまで、メソッドがブロックする。
  • 未処理メッセージ キューとネットワーク統計情報を監視する。キューにメッセージが少ないか、またはまったくない場合は、伝送速度を上げる。キューが大きいか、または急速に巨大化している場合は、伝送速度を下げ、できれば一部のメッセージを取り消す。詳細については、｢送信の優先順位付け｣にある送信タイムアウトの説明を参照すること。
  • プレーヤーごとに未処理メッセージ キューを分析する。メッセージの受信速度には、プレーヤーごとに相当な差があるかもしれない。その場合、一括の統計情報は参考にならない。グループへの送信ではなく、指名による送信を検討する。
  • 個々のメッセージに適したカテゴリを選択する。オーバーヘッドが最も大きいカテゴリは、最も重要なメッセージのために予約する。
  • メッセージに優先順位を付けて、最も重要なメッセージが、比較的重要でないメッセージのために遅れることなく、即座に送信されるようにする。
  • 未処理メッセージ キューが大きくなりすぎないようにする。未処理のメッセージが多いと、メッセージの伝送が遅れるだけでなく、メモリ リソースが大量に消費されることもある。
  • Send および SendTo メソッドのタイムアウト機能を使って、未処理メッセージ キューから古いメッセージを自動的に消去する。
  • メッセージあたりのデータ量を最小限に抑える。通常、大きいメッセージを少数送信するよりは、小さいメッセージを頻繁に送信した方がよい。
  • 未処理メッセージ キューを調べるときに、ループの間隔をあまり短くしないこと。間隔の短いループは、CPU サイクルの無駄である。代わりに、通常どの程度の時間で次の送信ができるようになるかを予想し、その時間スリープする方がよい。


アプリケーションにおける DirectX プロトコルの使い方

ここでは、アプリケーションから Microsoft® DirectPlay® プロトコルの機能をどのように使用できるかを説明する。

メッセージの送信には、5 つの DirectPlay オブジェクトを使用できる。

  • DirectPlay8Peer
  • DirectPlay8Client
  • DirectPlay8Server
  • DirectPlay8LobbyClient
  • DirectPlay8LobbiedApplication

メッセージを送信するには、使用するオブジェクトに応じて Send または SendTo というメソッドを呼び出す。これら 5 つのメソッドの使い方はほぼ同じだが、詳細は異なる。詳細については、該当するリファレンス ページを参照すること。

Send および Sendto メソッドでは、パラメータを使って DirectPlay プロトコルが持つ多くの機能を制御できる。たとえば、DirectPlay8Peer.SendTo の lFlags フィールドでは以下のことを指定できる。

  • メッセージの優先度。
  • 高信頼性か低信頼性か。
  • シーケンシャルか非シーケンシャルか。

詳細については、該当するメソッドのリファレンスを参照すること。

アプリケーションにメッセージが届くと、DirectPlay からメッセージ ハンドラの DirectPlay8Event.Receive メソッドが呼び出される。関連する型には、データ ブロックへのポインタと共に、メッセージの発信元といった情報が格納されている。


DirectPlay コールバック関数とマルチスレッドに関する問題

Microsoft® DirectPlay® と DirectPlay Voice では、DirectPlay が発行するイベントを処理するため、いくつかのコールバック関数を独自に実装する必要がある。DirectPlay はマルチスレッド化されているので、同時に複数のイベントを発行することがある。このため、重複する複数のコールバックがアプリケーションに届く可能性がある。

DirectPlay には、コールバックの指示に対応するために、スレッド プールが保持されている。コールバックは、DirectPlay が保持するプール内のスレッドから起動される。Microsoft Windows 2000 では、このスレッド プールのサイズをプロセスごとに構成できる。また、DirectPlay では、Windows 2000 上で動作するときに I/O 完了ポートを使用する。I/O 完了ポートは高度な問題であり、ここでは説明しない。この件については、MSDN (Microsoft Developer Network ) のドキュメントや、Win32 のマルチスレッドに関する現在入手可能なリファレンスを参照することを推奨する。

したがって、DirectPlay コールバックで正しく信頼性の高いデータ アクセスを行うには、同期をマルチスレッド化する手段を実装しなければならない。このことを、コールバックを "再入可能" または "スレッドセーフ" にする、と言う。

Microsoft Windows OS ファミリでは、現在、マルチスレッド環境でデータの同期をとるために、以下の 3 つの方法が用意されている。

  • ミューテックス オブジェクト
  • セマフォ オブジェクト
  • クリティカル セクション オブジェクト

クリティカル セクション オブジェクトを使って同期をとる方法は、DirectX 8.0 SDK に付属する DirectPlay の音声関連サンプルに示されている。ミューテックス オブジェクトまたはセマフォ オブジェクトを実装する場合、これらのトピックは、Microsoft Platform SDK にも、多くのリファレンス ブックにも記載されているので、参照すること。これらの同期手段は、万一何らかの問題が起きた場合、複雑で難しいデバッグ作業が必要になる。このため、いずれかを実装するには、個々の分野に関する相当進んだ知識がなければならない。

DirectPlay のスレッド モデルは、最高の効率が得られるように最適化されている。このため、"送信" 処理中、および受信メッセージを含む "指示" メッセージ中に、スレッド コンテキストが切り替わることはない。

ここでは、「DirectPlay のネットワーキング コールバック」について説明する。

詳細については、｢DirectPlay と DirectPlay Voice におけるコールバック関数の実装｣を参照すること。


DirectPlay のネットワーキング コールバック

ここでは、C++ でのアプリケーション開発について説明する。


DirectPlay Voice について

Microsoft® DirectPlay® Voice は、ネットワーク セッションおよびネットワーク転送を行う DirectPlay と統合された、フル音声通信 API である。

DirectPlay Voice は、音声の録音/再生を行うために、DirectSound とも統合されている。音声データを別々の再生バッファに振り分ける能力や、特殊オーディオ エフェクト (3D サウンド ポシショニングなど) の使用を含め、DirectSound が持つすべてのオーディオ機能が継承されている。

DirectPlay Voice のネットワーキング

DirectPlay Voice のトポロジ

音声ホストの移行

オーディオ デバイスのテスト

音声 CODEC

自動ゲイン制御

伝送制御

キャプチャ フォーカス

ジッター バッファ

ワーキング セットについてのガイドライン


DirectPlay Voice のネットワーキング

Microsoft® DirectPlay® Voice は、メディアに依存しないネットワーク転送とプレーヤー管理を行うために、DirectPlay セッションを使用する。DirectPlay Voice API のセッション制御機能は、DirectPlay とは異なっている。DirectPlay Voice が音声通信を送受信するためには、DirectPlay ネットワーク転送セッションも事前に作成されている必要がある。DirectPlay Voice は、IDirectPlay4 オブジェクトと IDirectPlay8 オブジェクトのいずれかを、ネットワーク転送に使用できる。

DirectPlay Voice をマルチプレーヤー ゲームと共に同時処理で使用している場合には、ゲーム固有のデータをやり取りするために、ゲームでも転送セッションを使用する可能性が高い。こうすると、ゲーム データと音声データの間でネットワーク リソースの使用を最適化することができる。

また、スタンドアロンの音声会議アプリケーションなどでは、音声セッション専用の転送セッションを作成して使ってもよい。


DirectPlay Voice のトポロジ

Microsoft® DirectPlay® Voice セッションは、音声通信の転送に DirectPlay ネットワーク セッションを使用する。ネットワーク セッションが作成されると、3 つのトポロジのいずれかを使用する DirectPlay Voice オブジェクトを作成できるようになる。

  • ピアツーピア音声トポロジ
  • 転送サーバー音声トポロジ
  • ミキシング サーバー セッション

選択すべきトポロジはさまざまな要素によって異なる。これらの要素については、DirectPlay Voice トポロジの各トピックで説明する。すべての音声トポロジが、あらゆる種類の DirectPlay ネットワーキング セッションを通じて転送できるとは限らないので、注意すること。


ピアツーピア音声トポロジ

ピアツーピア トポロジを採用している Microsoft® DirectPlay® Voice セッションでは、個々の音声セッション クライアントが、ほかのすべての音声セッション クライアントに、その音声オーディオ データを直接ストリームする。各クライアントは、流入する個々の音声オーディオ ストリームをすべて受け取り、受け取ったストリームをミキシングし、ミキシング済みの信号をクライアントのコンピュータで再生する。

ピアツーピア トポロジを採用する利点は、音声セッション内のコンピュータに、高い帯域幅やプロセッサ能力が要らないことにある。ただし、各クライアントのコンピュータにおける帯域幅とプロセッサの使用量は、出入りするオーディオ ストリームの数によって異なる。流出する音声オーディオ ストリームの数は、音声セッションに参加しているターゲットの数と等しい。ただし、後述するように、ネットワーク プロバイダが本来のマルチキャストを実行できる場合は例外である。流入する音声オーディオ ストリームの数は、ほかのいくつの音声セッション クライアントがそのクライアントをターゲットにしているか、およびほかのクライアントのうちいくつが話しているかによって異なる。

ゲーム設計の面から考えると、1 つの音声セッション クライアントを、6 ～ 8つを超えるクライアントがターゲットとすることは、実用的でない。6 ～ 8つのクライアントがすべて同時に話しだすと、会話が混乱し、クライアント間のやり取りが困難になる可能性がある。

DirectPlay ネットワーク セッションが本来のマルチキャストをサポートしていれば、流出する音声オーディオ ストリームの数を相当減らすことができる。全クライアントを 1 つのマルチキャスト ネットワークに含め、音声ストリームのターゲットを 1 つの DirectPlay グループにすると、流出するストリームはたった 1 つになる。

ピアツーピア音声トポロジを採用している DirectPlay 音声セッションは、DirectPlay8VoiceClient.Create3DSoundBuffer メソッドを使った音声データの 3D 空間化をサポートする。

ネットワーク転送がクライアント/サーバー セッションの場合には、音声ピアツーピア音声トポロジを採用している音声セッションを使用できないので、注意すること。


転送サーバー音声トポロジ

転送サーバー トポロジを採用している Microsoft® DirectPlay® 音声セッションでは、セッション内の 1 台のコンピュータが転送サーバーの役割をする。音声セッション内の各クライアントは、音声データを転送サーバーにストリームする。転送サーバーは、セッション内のほかのクライアントすべてに、この音声データを転送する。各クライアントが、転送サーバーから転送された流入オーディオ ストリームをすべて受け取る。最後に、各クライアントのコンピュータが、流入するストリームをミキシングして再生する。

転送サーバー トポロジを採用している音声セッションでは、流出する音声オーディオ ストリームが 1 つしかないため、個々のクライアントにおける流出帯域幅の要件は一定である。流入帯域幅とプロセッサの要件は、ピアツーピア トポロジを採用している音声セッションでの要件と同じだが、流入する音声オーディオ ストリームの数によって異なる。

転送サーバーによる DirectPlay 音声セッションでは、サーバーに個々のクライアントより大幅に高い帯域幅が必要になる。ただし、サーバー上では音声データの圧縮や圧縮解除が発生しないため、プロセッサ要件は高くない。このようにコンピュータのプロセッサへの負荷が減ることは、コンピュータ自体のパフォーマンスを悪化させることも、ゲーム サーバーや同じコンピュータで動作しているクライアント プログラムのパフォーマンスを悪化させることもなく、高い帯域幅で接続している個々のクライアントのコンピュータが、転送サーバーのホストとなれることを意味する。

ピアツーピア トポロジを採用している音声セッションでは、個々のクライアントにおける流出帯域幅の要件が、流入帯域幅の要件より大幅に高いのが普通である。したがって、流出帯域幅の要件をオーディオ ストリーム 1 つに減らせば、帯域幅の総使用量を大幅に減らすことができる。たとえば、8 人が参加している音声セッションで、全クライアントが互いの声を聞くことができる場合には、使用しているコンピュータで音声データがキャプチャおよび送信されるたびに、そのクライアントから 7 つの音声ストリームが流出する。ただし、全クライアントが同時に話すことはほとんどなく、同時に流入する音声ストリームは 2 ～ 3 つより少ないのが普通である。


ミキシング サーバー セッション

ミキシング サーバー セッションでは、セッション内の 1 台のコンピュータがミキシング サーバーの役割をする。各クライアントが、音声データをミキシング サーバーにストリームする。ミキシング サーバーは、個々の音声ストリームのターゲットを調べたうえで、適切な圧縮解除、ミキシング、および再圧縮を実行して、各クライアントに送るオーディオ データのミキシング済みストリームを生成する。各クライアントが、このミキシング済みの単独ストリームを受け取って再生する。

ミキシング サーバー セッション内のクライアントでは、個々のクライアントに、圧縮および送信すべき流出オーディオ ストリームが 1 つと、圧縮解除および再生すべき流入オーディオ ストリームが 1 つしかないため、流出帯域幅、流入帯域幅、および CPU の要件が簡単に予測できる。

ミキシング サーバーにおける帯域幅と CPU の要件は、クライアントより大幅に高い。通常、ミキシング サーバーは、1 台のコンピュータを完全に占有するか、または専用のゲーム サーバーとコンピュータを共有する。

ミキシング サーバー音声セッションは、DirectPlayVoiceClient8.Create3DSoundBuffer メソッドを使った音声データの 3D 空間化をサポートしない。

ミキシング サーバー音声セッションは、ピアツーピアまたはクライアント/サーバー転送セッションを使って実行できる。


音声ホストの移行

ピアツーピアの Microsoft® DirectPlay® ネットワーク セッションでは、ネットワーク セッション内の 1 つのクライアントがホストの役割をする。そのホストがセッションを抜けるか、または何らかの理由で応答しなくなると、セッション内のほかのクライアントがホストに選ばれる。

DirectPlay 音声セッションでは、ピアツーピア音声セッションで同様のホスト移行プロセスが発生する。ただし、音声ホストは DirectPlay ネットワーク セッションと無関係に移行する。音声ホストが移行するのは、サーバーが DirectPlayVoiceServer8.StopSession を呼び出したときか、または音声ホストが応答しなくなった場合である。音声ホストが移行すると、各クライアントの DirectPlayVoiceEvent8.HostMigrated メソッドが呼び出される。ローカル クライアントが新しい音声セッション ホストになった場合、NewServer パラメータは新たに作成された IDirectPlayVoiceServer オブジェクトを示す。ローカル クライアントは、このオブジェクトを使用してホスト サービスを提供できる。ローカル クライアントが新しいホストではない場合、NewServer パラメータは NULL になる。


オーディオ デバイスのテスト

マイクロフォンの設定は、DirectPlayVoiceTest8.CheckAudioSetup メソッドによってサポートされる。

このメソッドを呼び出すと、DirectX のオーディオ設定ウィザードが起動される。このウィザードは、テストを実行し、システムで全二重処理が正しくサポートされていることと、マイクロフォンと再生が適切に設定されていることを確認する。ウィザードは、選択した再生およびキャプチャ デバイスの組み合わせそれぞれにつき、1 回だけ実行する必要がある。アプリケーションでは、開始時に構成を毎回テストしなければならない。これには、lFlags パラメータを DVFLAGS_QUERYONLY に設定して DirectPlayVoiceTest8.CheckAudioSetup を呼び出す。こうすると、直前のテスト後にデバイス構成が変化したかどうかを簡単に調べられる。デバイスがテストされていなければ、DirectPlayVoiceTest8.CheckAudioSetup をもう一度実行してウィザードを起動する。直前のテスト後に構成が変化した場合、ウィザードをもう一度実行していなければ、DirectPlayVoiceClient8.Connect が DVERR_RUNSETUP を返し、DirectPlay Voice を初期化できない。

ユーザーのサウンド カードに全二重能力がないと、音声通信を聞くことしかできない。音声通信を送信できないのは、通常、ゲームではオーディオ カードが再生モードになっているためである。問題を避けるため、DirectX 8.0 では再生とキャプチャを動的に切り替えられないようになっている。DirectX のオーディオ設定ウィザードを使用すると、システムの全二重能力に関するフィードバックが得られる。

現在でも、実際に使用されているシステムに全ニ重のサウンド カードが装備されていない場合は少なくないので、注意が必要である。全ニ重サウンド カードは 1998 年に普及したが、当時のオーディオ カード ドライバで全ニ重処理が有効なものは少ない。1999 年に新しいシステムを購入した場合や、1999 年にドライバをアップグレードした場合には、全二重能力がある可能性が高い。


音声 CODEC

Microsoft® DirectPlay® で専用に提供される圧縮/圧縮解除 (CODEC) アルゴリズムは、音声品質の CODEC である。これらのアルゴリズムは、すべて 8 kHz の 16 ビット モノラル形式に基づいている。サードパーティの CODEC はサポートされない。また、DirectPlay Voice と共に使用する独自の CODEC を作成することはできない。

帯域幅の要件が低くなると、音声データのオーディオ品質も低下するので、注意が必要である。

ゲームの音声セッション内で、CODEC を動的に切り替えることはできない。1 つの音声セッション内では、すべてのユーザーが同じ CODEC を使用する必要がある。ただし、適切なユーザー インターフェイスを作成し、そこで現在のセッションを破棄し、別の CODEC を使った新しいセッションを作成することによって、CODEC を強制的に切り替えることも可能である。ゲーム アプリケーションのユーザーが、ロビー チャットからゲームにジャンプしている場合には、この方法が適している。

ほかのすべてのゲーム設定パラメータと同様に、使用される CODEC はホストが制御しなければならない。音声セッション ホストとゲーム データのホストは、同一でなくてよい。

どのような形のネットワーク通信でも同じだが、音声通信の負荷を分析して、ゲーム データと音声データの通信に必要な帯域幅が確保できるかどうかを確認することが重要である。音声による帯域幅の使用量は、簡単に分析できる。同時に発生すると思われる音声ストリームの数を予測し、CODEC およびプロトコル オーバーヘッドに必要な帯域幅の合計を、その数に乗算する。

CODEC の選択では、CPU の消費というもう 1 つの要素も考慮する必要がある。通常、帯域幅の低い CODEC でさえ、200 MHz Pentium プロセッサであれば、音声ストリームのエンコードのためにリソースの約 8 %、デコードのためにさらに 4 % が必要である。ネットワークの帯域幅と同様に、CPU リソースの消費もストリーム数に応じて増加する。


自動ゲイン制御

Microsoft® DirectPlay® Voice には、できるだけ良好な録音入力レベルを提供するために、サウンド カード上のハードウェア入力音量を自動調整する機能が用意されている。自動ゲイン制御を有効にするには、クライアント構成を設定するときに、DVCLIENTCONFIG 構造体の lFlags メンバに DVCLIENTCONFIG_AUTORECORDVOLUME フラグを設定する。自動ゲイン制御のアクティブ/非アクティブは、音声セッション内でいつでも切り替えることができる。

ゲーム アプリケーションでは、なるべく自動ゲイン制御を使用すること。自動ゲイン制御を使用すると、ゲーム リソースがほんの少し必要になるが、ゲーム内で録音音量を制御しないで済む。ユーザーは、わざわざレベル設定をせずに、高品質で音声を送受信することができる。


伝送制御

Microsoft® DirectPlay® Voice のパフォーマンス要件を抑えるには、ユーザーが話しているときにだけ、音声データを送信すればよい。音声データの伝送を制御するには、2 つの方法がある。使用すべき方法は、ゲームの設計要件によって異なる。

  • 音声をアクティブにする
  • プッシュツートーク


音声をアクティブにする

音声をアクティブにすることによる伝送制御では、マイク入力を常時分析することにより、ユーザーが話しているかどうかを判断する。音声をアクティブにするには 2 つの利点がある。ユーザーはマイクロフォンに話しかけるだけでよい。また、音声セッションの接続時に、DVCLIENTCONFIG 構造体の lFlags パラメータを DVCLIENTCONFIG_AUTOVOICEACTIVATED に設定するだけで済むので、簡単にコーディングできる。

ただし、音声をアクティブにするには 1 つ欠点があり、ユーザーの息が直接マイクロフォンにかかった場合、騒がしい環境などで雑音が多い場合、ゲームのオーディオを外部スピーカで再生している場合などに、その音が原因で不要な音声がアクティブになる可能性がある。品質のよくないマイクロフォンでは、この可能性が特に高くなる。


プッシュツートーク

プッシュツートーク伝送制御では、音声データを送信するタイミングを、ユーザーが積極的に選択する。この伝送制御方法を使用すると、音声以外のデータが送信される危険がない。この方法は、双方向無線機で [Talk] ボタンを押すのと同じであり、ある種のゲーム (対面型のシューティング ゲームなど) では、この機能によってリアリティが増す。この方法には、話すタイミングをユーザーが積極的に選択しなければならないため、同時に話すユーザーの数が減るという利点もある。ユーザー制御の機能が必要なため、この伝送制御は音声をアクティブにすることにより設計と開発に時間がかかる。


キャプチャ フォーカス

ここでは、C++ でのアプリケーション開発について説明する。


ジッター バッファ

Microsoft® DirectPlay® Voice には、ジッター バッファという特徴的な機能がある。ジッター バッファは、最小限の遅延時間で最適な音質を提供する、柔軟なバッファリング アルゴリズムである。

混雑したネットワークでは、音声データ情報の各パケットが、ホスト コンピュータでエンコードされたときと異なった順序で届くことがある。音声データは本来連続したものなので、パケットが万一遅れても受信して順序よく再生するために、これらの流入パケットは、しばらくキューに入れておく必要がある。

音声通信の品質を最大にするようにジッター バッファを設定すると、必要な数の音声パケットが届き、再生用のキューに入るまでに、時間がかかる。このために音声が遅れ、音声通信をリアルタイムに聞くことができない。代わりに、音声データが聞こえるタイミングは、録音より数ミリ秒から数秒ほど遅れる可能性がある。プレーヤーが協力し合うゲームでは、この遅れによって問題が発生する。ゲーム内でイベントが発生したときに、プレーヤーがそれらのイベントに基づいてリアルタイムに情報をやり取りできないからである。たとえば、対面型のシューティング ゲームで、プレーヤーが背後から攻撃されそうになって仲間が警告しようとしても、攻撃されてしまうまで音声通信が聞こえない可能性がある。

遅延時間を減らすようにジッター バッファを設定すると、キューを一杯にするために必要なパケット数が少なくなる。ただしこの場合、連続パケットの一部が間に合わず、その結果、再生時にバッファ内に音声データが揃っていない可能性がある。音声通信が聞こえるタイミングは、実際の録音とほぼ一致している。ただしこの場合、音声が "こま切れ" で品質は低い。

DirectPlay ジッター バッファでは、最小限の遅延時間で最高品質の音声通信を提供する方法を、2 つの方法により判断する。最初に、ネットワークの状態を監視して、遅れや混雑状況を判断する。次に、音声の中断を最小限に抑えながら遅延時間を可能な限り短縮するため、ジッター バッファ (またはキュー) のサイズを動的に調整する。

DirectPlay Voice ジッター バッファは、ネットワークの状態に合わせて自動的に調整される (デフォルト動作の場合)。アルゴリズムでネットワークの状態をどの程度厳密に追跡するかは、DVCLIENTCONFIG 構造体の lBufferAggressiveness メンバとlBufferQuality メンバを使って手動で調整できる。アグレッシブネスのレベルを上げるほど、ネットワークの状態が厳密に監視される。通常、dwBufferQuality の値が高いほど、音質は上がるが遅延時間は長くなる。また、値が小さいほど、遅延時間は短くなるが質は低下する。

アグレッシブネスのレベルは、ゲーム アプリケーション実行中のネットワーク状態に合わせて選択することが重要である。ネットワーク パフォーマンスが安定しているときに高レベルのアグレッシブネスが選択されていると、一時的な問題が誤まって解釈され、存在しないかもしれない問題が過剰に補正される可能性があるためである。


ワーキング セットについてのガイドライン

転送トポロジ、音声トポロジ、伝送制御、および CODEC の最適な構成は、開発するゲームの種類やジャンル、1 つのゲーム セッションに参加するプレーヤーの数、およびターゲットとなる接続の種類に基づいて判断する。

音声セッションに参加するプレーヤーの数は、ゲーム セッションに実際に参加するプレーヤーの数と等しいとは限らないので、注意が必要である。たとえば、対面型のシューティング ゲームを開発する場合には、ゲーム内で期限付きのパワーアップ アイテムとして提供される無線機や発信機で、音声通信を表現できる。無線機として表現すると、車内や移動しない司令部内にある無線機に、通信を制限できるという利点もある。

2 番目の例として、同時に 4 人がプレーするオンライン ブリッジ ゲームについて考えよう。ワーキング セットが小さいので、ピアツーピア ネットワーク トポロジ上でピアツーピア音声トポロジを転送する方法が適している。この小さなワーキング セットでは、伝送制御のモードとして、音声をアクティブにすることもできる。ピアツーピア音声トポロジは、実装が容易で、プレーヤーがサーバーの役割をしないでよい。4 人のプレーヤー全員が Voxware SC6 CODEC を使用すると、最大帯域幅は、CODEC のプロトコル オーバーヘッドを含め、スピーチ ストリームあたり 4.2 Kbps となる。さらに、ゲーム データに必要な帯域幅が無視できる程度に小さいとすると、話者それぞれの流出における最大の帯域幅要件は、残り 3 人へのストリーム 3 つ (つまり 12.6 Kbps) となる。また、流入における帯域幅は、どのクライアントでも 0 (残り 3 人が黙っているとき) ～ 12.6 Kbps (残り 3 人全員が話しているとき) となる。CPU は、エンコードのために 8 %、デコードのために 0 ～ 12 % が必要である。この結果、最悪の場合の要件は 25.2 Kbps となる。したがって、各プレーヤーは 14,400 ボー以上のモデムを使用する必要がある。

もう 1 つの例として、32 人までのプレーヤーが 2 チームに分かれて戦うチーム対戦型コンバット ゲームについて考える。ゲーム データには、28,800 ボーのモデムが必要なものとする。この例では、プレーヤー数が多いので、転送サーバー音声トポロジが適している。ここでも、プレーヤー全員が Voxware SC6 CODEC を使用するとすると、最大帯域幅は前述のブリッジ ゲームと同様に 4.2 Kbps となる。この例では、話しているときに 4.2 Kbps が流出し、チームからは最大 12.6 Kbps が流入する。CPU は、Pentium 200 であれば、エンコードのために 最大 8 %、受信のために最大 12 % が必要である。したがって、ゲーム データのための 28.8 Kbps と、大きくなった流入帯域幅 12.6 Kbps のために、各プレーヤーは 41,400 ボー以上のモデムを使用する必要がある。

転送サーバー自体にとって最悪のケースは、32 人が全員同時に話す場合であり、このときには 134.4 Kbps が必要になる。サーバーの CPU 使用量はごく限られている。これは、サーバーがストリームのエンコード/デコードを行わないためである。サーバーはストリームをリダイレクトするに過ぎない。通常は、16 人が同時に話すものとして、67.2 Kbps が必要になる。

ミキシング サーバー音声トポロジを選ぶ場合と、転送サーバー音声トポロジを選ぶ場合の差異を説明するため、ここでも前述のプレーヤー 32 人による対戦型コンバット ゲームについて考える。ミキシング サーバー音声トポロジを使用すると、各クライアントでは、送信のために 4.2 Kbps、受信のために 4.2 Kbps が必要になる。最悪の場合の帯域幅要件は、8.4 Kbps に下がる。また、CPU 要件は、200 MHz で動作する Pentium プロセッサの 12 % である。この結果、クライアントのモデム要件も 33,600 ボーに下がる。

サーバー側では、CPU 負荷が変わる。サーバーは、流入するストリームをすべてデコードおよび再エンコードし、必要に応じてストリームのミキシングも行う。ストリームをミキシングするための CPU 負荷は、比較的低いので無視する。最悪のケースは、同時に 32 のストリームをデコード/エンコードする場合である。この場合、音声サービス単独でも、400 MHz で動作する Pentium II プロセッサが最低限必要になる。


DirectPlay の使い方

Microsoft® DirectPlay® ドキュメントのこのセクションでは、マルチプレーヤー アプリケーションの重要な要素のいくつかを、DirectPlay API を使って実装する方法を説明する。

  • DirectPlay 列挙の使い方
  • ロビー クライアントの実装
  • ロビー可能アプリケーションの実装
  • Netmon を使った DirectPlay ネットワーク トラフィックの監視
  • DirectPlay と DirectPlay Voice におけるコールバック関数の実装
  • クリティカル セクション オブジェクトを使った DirectPlay ネットワーキング コールバックの実装
  • DirectPlay DPNSVR アプリケーションの使い方


DirectPlay 列挙の使い方

列挙とは、Microsoft® DirectPlay® がアプリケーションに情報を提供する方法の 1 つである。列挙は、いくつかの似通った要素についてデータを集めるために使用する。たとえば、セッション内の個々のプレーヤーに関する情報は、列挙を使って取得できる。列挙を実行するには、アプリケーションが DirectPlay にある種類の情報を照会し、DirectPlay が関連要素それぞれのデータ型を返す。通常、このデータは型の配列として返される。

多くのアプリケーションでは、列挙を少なくとも 1 回実行する必要があり、繰り返し実行しなければならない場合も少なくない。個々の DirectPlay オブジェクトでは、それぞれ異なる列挙セットがサポートされる。したがって、詳細はアプリケーションによって異なる。以下は、利用可能な列挙と、各種の列挙をサポートするオブジェクトの一覧である。

  • セッション ホスト (DirectPlay8Peer、DirectPlay8Client)
  • サービス プロバイダ (DirectPlay8Peer、DirectPlay8Client、DirectPlay8Server)
  • プレーヤー (DirectPlay8Peer、DirectPlay8Server)
  • グループ (DirectPlay8Peer、DirectPlay8Server)
  • グループ メンバ (DirectPlay8Peer、DirectPlay8Server)
  • ローカル プログラム (DirectPlay8LobbyClient)

詳細については、「DirectPlay 列挙の実装」を参照すること。


DirectPlay 列挙の実装

多くの DirectPlay 列挙は、列挙すべき項目の数を判断し、適切な列挙メソッドを呼び出す、という標準パターンに従う。ホストの列挙は、このパターンに従わないので別に説明する。

次の手順は、ピアツーピア ゲームのグループのメンバを列挙する方法の概要である。ホストの列挙を除き、ほかの種類の列挙もすべて同様の一般手順に従って行われる。

  1. DirectPlay8Peer.GetCountGroupMembers を呼び出す。このメソッドは、グループのメンバ数を返す。
    1. グループの各メンバについて、DirectPlay8Peer.GetGroupMember を 1 回ずつ呼び出す。メソッドは、指定したプレーヤーの ID を返す。

詳細については、「ホストの列挙」を参照すること。


ホストの列挙

セッションを準備する 1 つの方法は、セッション ホストが利用可能になったことを本人に通知させることである。この種のセッションを、"ある要素を全要素にコピーするセッション" と言う。ピアまたはクライアントは、利用可能なホストを列挙し、1 つを選択し、接続要求を送信してそのゲームに参加することにより、参加するゲームを探すことができる。詳細については、「ピアツーピア セッション」または「クライアント/サーバー セッション」を参照すること。

ほかの列挙と異なり、利用可能なホストの要求に応答するために必要な情報は、ローカル コンピュータに記憶されていない。代わりに、クライアントまたはピアが要求を (たとえばローカル サブネット上で) 全要素にコピーし、利用可能なホストからの応答を待つ必要がある。一方、ホストは、これらの要求を待ってから適切に応答する必要がある。このように、自分がセッション メンバの候補かセッション ホストかによって、手順は微妙に異なる。

次の手順は、ピアツーピア セッションに利用可能なホストの列挙方法を示している。クライアント/サーバー セッション用の手順も、基本的にこれと同じである。DirectPlay8Peer.EnumHosts は、列挙を開始するメソッドである。主要な設定パラメータは、ApplicationDesc、Deviceinfo、および AddrHost である。

  1. プレーしたいゲームの GUID を DPN_APPLICATION_DESC 型の guidApplication メンバに割り当て、それを ApplicationDesc パラメータに割り当てる。
  2. 対象のデバイスの DirectPlay8Address オブジェクトを作成し、それを Deviceinfo に割り当てる。このオブジェクトには、ネットワーク接続の確立に必要な情報が格納されている。
  3. 利用可能なホストを特定のコンピュータに照会するには、ホスト コンピュータに対応する DirectPlay8Address オブジェクトを作成し、それを pdpaddrHost に割り当てる。このオブジェクトが空の場合、DirectPlay は pdpaddrDeviceinfo に格納された情報に基づいてアドレスを作成する。アドレス オブジェクトの詳細については、「DirectPlay アドレシング」を参照すること。通常、IP または IPX サービス プロバイダを使用している場合は、この結果、使用中のローカル サブネットへ照会はある要素を全要素にコピーする。
  4. DirectPlay8Peer.EnumHosts を呼び出す。
  5. この結果、DirectPlay は、メッセージ ハンドラの DirectPlay8Event.EnumHostsResponse メソッドに対し、応答するホストそれぞれにつき 1 回ずつ一連の呼び出しを行う。
    1. メッセージ ハンドラに返された情報を調べ、セッションを選択し、DirectPlay8Peer.Connect を呼び出してそのセッションへの参加を要求する。

ある要素を全要素にコピーするセッションのホストとなるには、自分が利用可能なことを通知し、照会または接続要求を待つ。次の手順はピアツーピア ホストに適用されるが、クライアント/サーバー ホスト用の手順も基本的にこれと同じである。

  1. DirectPlay8Peer.SetPeerInfo を呼び出して、プレーヤー用の静的な設定を指定する。
  2. DPN_APPLICATION_DESC 型に値を割り当てることにより、ゲームの構成を指定する。
  3. DirectPlay8Peer.Host を呼び出して、自分がホストの候補であることを通知する。AppDesc パラメータを、この前のステップで定義した DPN_APPLICATION_DESC 型に設定する。
  4. 列挙要求を待つ。列挙要求は、メッセージ ハンドラの DirectPlay8Peer.EnumHostsQuery メソッドへの呼び出しの形をとる。列挙要求に応答するには、DPN_APPLICATION_DESC 型の内容を設定し、fRejectMsg を FALSE に設定する。
  5. ピアがセッションへの参加を決めると、DirectPlay からメッセージ ハンドラの DirectPlay8Event.IndicateConnect メソッドが呼び出される。

ゲームを準備および起動する方法の詳細については、「ピアツーピア セッション」および「クライアント/サーバー セッション」を参照すること。


プレーヤー コンテキスト値の使い方

ここでは、C++ でのアプリケーション開発について説明する。


プレーヤー コンテキスト値の定義

ここでは、C++ でのアプリケーション開発について説明する。


プレーヤー コンテキスト データの管理

ここでは、C++ でのアプリケーション開発について説明する。


ロビー クライアントの実装

ロビー クライアントとは、ユーザーのコンピュータに常駐するアプリケーションである。主な役割は、ユーザーのコンピュータにあるゲーム アプリケーションと、リモート コンピュータにあるロビー サーバーをリンクすることにある。ただし、ロビー クライアントは、スタンドアロン アプリケーションとしても機能する。たとえば、特定の LAN サブネットのユーザーによるゲーム セッションは、これらを使って準備できる。

ロビー クライアントは、通常、以下の作業をする 3 つの主要コンポーネントから構成される。

  • 外部 (ロビー サーバーまたはほかのロビー クライアント) との通信。
  • ユーザーとの通信。主にグラフィカル ユーザー インタフェース (GUI) を使用する。
  • Microsoft® DirectPlay® との通信。

DirectPlay では、前の 2 項目の実装方法が指定されていない。ロビー クライアント ベンダーが、個々の製品に適した方法で実装しなければならない。DirectPlay は、DirectPlay と通信し、ユーザーのロビー可能なゲーム アプリケーションと DirectPlay を通じて通信するために、ロビー クライアントが使用できる標準 API を提供する。

ここでは、ロビー クライアントの実装に関する以下の重要な項目について説明する。

  • ロビー クライアントの初期化
  • ロビー対象アプリケーションの起動
  • ロビー クライアント メッセージ ハンドラの実装
  • ロビー対象アプリケーションとの通信
  • ロビー クライアントの終了

簡単なロビー クライアントの完全な実装例については、サンプル アプリケーション LobbyClient を参照すること。


ロビー クライアントの初期化

ロビー クライアントは、ロビー サーバーが起動するか、ユーザーが直接起動する。ロビー クライアントは、起動しても、初期化されるまでアプリケーションを起動できない。初期化には、以下の作業が必要になる。

  • DirectPlay8LobbyClient オブジェクトを作成する。
  • DirectPlay8LobbyEvent オブジェクトを作成する。DirectPlay8LobbyEvent オブジェクトは、本来、ロビー クライアント オブジェクトからは直接、アプリケーションからは間接的に、メッセージを受け取るメッセージ ハンドラである。このオブジェクトは、Microsoft® DirectPlay® から提供されないので、アプリケーションで実装する必要がある。
  • このオブジェクトは、DirectPlay8LobbyClient.RegisterMessageHandler を呼び出して DirectPlay に登録しなければならない。
  • DirectPlay8LobbyClient.GetLocalProgram メソッドを使って、ユーザーのシステムにあるロビー可能なアプリケーションを列挙する。

前の 2 つのステップで、ロビー クライアント オブジェクトを作成し、そのオブジェクトとロビー クライアントの間に通信リンクを設定する。最後のステップで、ユーザーのシステムで利用できるロビー可能なアプリケーションを判断する。この情報は、選択されたアプリケーションを起動するために必要である。

登録済みアプリケーションのアプリケーション GUID は、アプリケーションの起動に必要なので、保存しなければならない。

ロビー クライアントの設計によっては、以下の作業のいくつかを実行する必要がある。

  • ロビー サーバーとのリンク確立など、Microsoft® DirectPlay® と関係のない初期化を実行する。
  • DirectPlay8Peer または DirectPlay8Client オブジェクトを作成する。
  • ピア オブジェクトまたはクライアント オブジェクトの列挙メソッドを使って、利用可能なサービス プロバイダ、アダプタなどを列挙する。


ロビー対象アプリケーションの起動

ユーザーがアプリケーションを選択し、ユーザーのシステムにそのアプリケーションが登録されていることをロビー クライアントが確認すると、アプリケーションを起動できるようになる。これには、DirectPlay8LobbyClient.ConnectApplication を呼び出す。最初のパラメータは、アプリケーションの起動に必要な各種の情報 (以下を含む) が格納された DPL_CONNECT_INFO 構造体である。

  • アプリケーションを識別する GUID。
  • 接続の設定 (ユーザーの Microsoft® DirectPlay® アドレスを含む)。DirectPlay アドレスの詳細については、「DirectPlay アドレシング」を参照すること。
  • アプリケーションがホストとなるかどうか。

DirectPlay8LobbyClient.ConnectApplication メソッドは、以降のすべての通信でアプリケーションの識別に使用するアプリケーション ハンドルを返す。アプリケーションが起動し、接続の確立が成功すると、DirectPlay がメッセージ ハンドラの DirectPlay8LobbyEvent.Connect メソッドを呼び出す。

注 DirectPlay8LobbyClient.ConnectApplication メソッドが成功コードを返して接続を確認する前に、メッセージ ハンドラの DirectPlay8LobbyEvent.Connect メソッドが呼び出されることがある。メッセージ ハンドラは、メソッドから復帰していなくても、メッセージを処理できなければならない。


ロビー クライアント メッセージ ハンドラの実装

メッセージ ハンドラは、ロビー クライアント オブジェクトからは直接、アプリケーションからは間接的に、メッセージを受け取る DirectPlay8LobbyEvent オブジェクトである。メッセージ ハンドラは、DirectPlay から提供されないので、アプリケーションで実装する必要がある。

メッセージ ハンドラは、以下のメソッドをすべて実装する必要がある。

  • DirectPlay8LobbyEvent.Connect
  • DirectPlay8LobbyEvent.ConnectionSettings
  • DirectPlay8LobbyEvent.Disconnect
  • DirectPlay8LobbyEvent.Receive
  • DirectPlay8LobbyEvent.SessionStatus

これらのメソッドの大半は、ゲームの状態が変化したとき、またはロビー クライアントが情報を要求したときに、DirectPlay が呼び出す。ただし、DirectPlay8LobbyEvent.Receive は例外である。このメソッドは、ゲーム アプリケーションからロビー クライアントにデータを直接渡すために呼び出される。

DirectPlay8LobbyEvent.Connect

このメソッドは、ロビー可能なアプリケーションの起動後に、DirectPlay が呼び出す。このメッセージは、アプリケーションの接続が成功したことを示す。関連する DPL_MESSAGE_CONNECT 型には、以下を含む各種の情報が保持される。

  • 接続 ID。ロビー クライアントが、DirectPlay8LobbyClient.Send でアプリケーションにデータを送信するか、または DirectPlay8LobbyClient.ReleaseApplication で接続を解放する必要があるときは、この ID を使用する。
  • ロビー接続データ。
  • 接続コンテキスト値 (省略可能)。

DirectPlay8LobbyEvent.ConnectionSettings

このメッセージ メソッドは、関連付けられたロビー可能なアプリケーションから、セッションの接続を修正するために DirectPlay8LobbiedApplication.SetConnectionSettings メソッドが呼び出されるたびに、DirectPlay が呼び出す。関連付けられた DPL_MESSAGE_CONNECTION_SETTINGS 型には、更新済みの接続情報が格納される。

DirectPlay8LobbyEvent.Disconnect

このメソッドは、ロビー可能なアプリケーションが DirectPlay8LobbiedApplication.Close を呼び出してセッションから抜けるときに、呼び出す。ロビー クライアント アプリケーションでは、接続をそのリストから削除し、アプリケーションに関連付けられたデータをすべて解放しなければならない。

DirectPlay8LobbyEvent.Receive

このメソッドを使用すると、DirectPlay8LobbiedApplication.Send を呼び出してアプリケーションからロビー クライアントにデータを渡すことができる。DirectPlay は、アプリケーションからロビー クライアントに、DPL_MESSAGE_RECEIVE 型を使ってデータ ブロックを渡す。このデータの処理は、ロビー クライアントが行わなければならない。

DirectPlay8LobbyEvent.SessionStatus

このメソッドは、セッションの状態に以下の 6 つの変化のいずれかが発生するたび呼び出す。

  • セッションが接続された。
  • セッションが接続できない。
  • セッションが切断された。
  • セッションが終了した。
  • セッション ホストが移行した。
  • このコンピュータがセッション ホストになった。

状態変化の種類は、メソッドの status パラメータの値によって示される。

詳細については、「ロビー クライアント メッセージ ハンドラのサンプル」を参照すること。


ロビー クライアント メッセージ ハンドラのサンプル

ここでは、C++ でのアプリケーション開発について説明する。


ロビー対象アプリケーションとの通信

ロビー クライアントと関連するアプリケーションのやり取りの大半は、間接的に行われる。ロビー クライアントがアプリケーションに影響する何らかの処理を実行 (または逆にアプリケーションがロビー クライアントに影響する何らかの処理を実行) すると、Microsoft® DirectPlay® が適切なメッセージを送信する。たとえば、ロビー クライアントが接続の設定を変更すると、DirectPlay がアプリケーションに通知し、新しい設定内容を提供する。ただし、DirectPlay8LobbyClient.Send メソッドを使用すれば、ロビー クライアントからアプリケーションにメッセージを直接送信することができる。DirectPlay はアプリケーションにデータをそのまま渡す。そのデータの処理は、アプリケーションが行わなければならない。

ロビー対象アプリケーションも、ロビー クライアントにデータを直接送信することができる。DirectPlay は、ロビー クライアント メッセージ ハンドラの DirectPlay8LobbyEvent.Receive メソッドを呼び出して、データを転送する。DirectPlay はロビー クライアントにデータをそのまま渡す。このデータの処理は、ロビー クライアントが行わなければならない。


ロビー クライアントの終了

セッションを閉じる準備ができたら、DirectPlay8LobbyClient.ReleaseApplication を呼び出してアプリケーションを切断する。Microsoft® DirectPlay® は、そのメッセージ ハンドラの DirectPlay8LobbyEvent.Disconnect メソッドを呼び出して、通知を求める。

アプリケーションを解放したら、必要に応じてクリーンアップを実行し、DirectPlay8LobbyClient.Close を呼び出してセッションを閉じる。


ロビー可能アプリケーションの実装

ロビー可能アプリケーションは、ロビー クライアントと正しく連動するように設計される必要がある。ロビー クライアントは任意のアプリケーションを起動できるが、Microsoft® DirectPlay® からのメッセージ、およびロビー クライアントからのメッセージを受け取れるのは、"ロビー起動" アプリケーションだけである。ロビー起動されるアプリケーションは、適切に登録されていて、DirectPlay ロビー対象アプリケーション オブジェクトを使って、DirectPlay およびロビー クライアントと通信できなければならない。

ここでは、ロビー可能アプリケーションの実装方法について説明する。

  • ロビー可能アプリケーションの登録
  • ロビー起動の取り扱い
  • ロビー対象アプリケーション コールバック メッセージ ハンドラの実装
  • ロビー クライアントとの通信
  • ロビー対象アプリケーションの終了


ロビー可能アプリケーションの登録

ロビー可能アプリケーションをロビー起動するには、事前に登録する必要がある。この登録は、1 回だけ実行される必要があり、通常はアプリケーションのセットアップ手順に含まれる。アプリケーションをロビー可能アプリケーションとして登録するため、レジストリを直接修正しようとしてはならない。代わりに、以下の処理を実行する。

  • DirectPlay8LobbiedApplication オブジェクトを作成する。
  • DirectPlay8LobbiedApplication.RegisterProgram を呼び出す。このメソッドは、情報を受け取り、適切なレジストリのキーと値を作成する。

DirectPlay8LobbiedApplication.RegisterProgram には、以下を含む各種の情報を提供する必要がある。

  • アプリケーションの識別に使用する GUID。
  • アプリケーションのフレンドリ名。
  • アプリケーションの実行ファイルの場所と名前。
  • "ランチャ" アプリケーション (省略可能) の場所と名前。
  • 起動時に実行ファイルに渡さなければならないコマンドライン引数。

Microsoft® DirectPlay® は、ゲーム アプリケーションではなく、ランチャ アプリケーションを起動する。次に、ランチャ アプリケーションがゲームを起動する。ランチャ アプリケーションは、たとえば違法コピー対策として使用できる。

プログラムの登録を解除するには、DirectPlay8LobbiedApplication.UnregisterProgram を呼び出す。このメソッドは、DirectPlay8LobbiedApplication.RegisterProgram で作成されたレジストリ エントリを削除する。


ロビー起動の取り扱い

ロビー可能アプリケーションが起動されたときにまず実行しなければならないのは、Microsoft® DirectPlay® ロビー対象アプリケーション オブジェクトの作成および初期化である。これには、以下の処理を実行する。

  • DirectPlay8LobbiedApplication オブジェクトを作成する。
  • DirectPlay8LobbyEvent メッセージ ハンドラ オブジェクトを作成する。
  • DirectPlay8LobbiedApplication.RegisterMessageHandler を呼び出して、メッセージ ハンドラ オブジェクトを登録する。

アプリケーションがロビー起動されている場合は、DirectPlay から DirectPlay8LobbyEvent.Connect メソッドが呼び出される。dlNotify パラメータには、セッション メンバのアドレス オブジェクトといった接続情報が付いた DPL_MESSAGE_CONNECT 型が格納される。

アプリケーションがロビー起動されていない場合は、DirectPlay8LobbiedApplication.SetAppAvailable を呼び出すと、ロビー クライアントからアプリケーションに接続可能であることを示すことができる。このメソッドは、通常、ユーザーがアプリケーションを起動したときに呼び出される。ただし、ユーザーが 1 つのセッションを閉じたが、アプリケーションがまだ動作していて、別のセッションで利用可能な場合にも、このメソッドを使用することができる。どちらの場合も、ロビー クライアントがアプリケーションをセッションに接続すると、DirectPlay からメッセージ ハンドラの DirectPlay8LobbyEvent.Connect メソッドが呼び出される。


ロビー対象アプリケーション コールバック メッセージ ハンドラの実装

メッセージ ハンドラは、ロビー クライアント オブジェクトからは直接、アプリケーションからは間接的に、メッセージを受け取る DirectPlay8LobbyEvent オブジェクトである。このオブジェクトは、Microsoft® DirectPlay® から提供されないので、アプリケーションで実装する必要がある。

メッセージ ハンドラは、以下のメソッドをすべて実装する必要がある。

  • DirectPlay8LobbyEvent.Connect
  • DirectPlay8LobbyEvent.ConnectionSettings
  • DirectPlay8LobbyEvent.Disconnect
  • DirectPlay8LobbyEvent.Receive
  • DirectPlay8LobbyEvent.SessionStatus

これらのメソッドの大半は、ゲームの状態が変化したとき、またはロビー対象アプリケーションが情報を要求したときに、DirectPlay が呼び出す。ただし、DirectPlay8LobbyEvent.Receive は例外である。このメソッドは、ロビー クライアントからゲーム アプリケーションにデータを直接渡すために呼び出される。

DirectPlay8LobbyEvent.Connect

アプリケーションをセッションに接続するために、ロビー クライアントが DirectPlay8LobbyClient.ConnectApplication を呼び出すと、このメソッドが呼び出される。関連する DPL_MESSAGE_CONNECT 型には、以下を含む各種の情報が保持される。

  • 接続 ID。ロビー クライアントが、DirectPlay8LobbyClient.Send でアプリケーションにデータを送信するか、または DirectPlay8LobbyClient.ReleaseApplication で接続を解放する必要があるときは、この ID を使用する。
  • ロビー接続データ。
  • 接続コンテキスト値 (省略可能)。

DirectPlay8LobbyEvent.ConnectionSettings

DirectPlay は、関連付けられたロビー クライアントから、セッションの接続を修正するために DirectPlay8LobbyClient.SetConnectionSettings メソッドが呼び出されるたびに、このメソッドを呼び出す。関連付けられた DPL_MESSAGE_CONNECTION_SETTINGS 型には、更新済みの接続情報が格納される。

DirectPlay8LobbyEvent.Disconnect

このメッセージは、ロビー クライアントが DirectPlay8LobbyClient.ReleaseApplication を呼び出してアプリケーションをセッションから切断するときに、送信される。アプリケーションでは、接続をそのリストから削除し、セッションに関連付けられたデータをすべて解放しなければならない。

DirectPlay8LobbyEvent.Receive

このメッセージを使用すると、ロビー クライアントからアプリケーションにデータを渡すことができる。ロビー クライアントが DirectPlay8LobbyClient.Send を呼び出すと、DirectPlay が DirectPlay8LobbyEvent.Receive を呼び出してデータをアプリケーションに渡す。このデータの処理は、アプリケーションが行わなければならない。

DirectPlay8LobbyEvent.SessionStatus

DirectPlay は、ロビー可能アプリケーション メッセージ ハンドラのために、このメソッドを呼び出さない。このメソッドは実装の必要があるが、ただ 0 を返してもよい。


ロビー対象アプリケーション メッセージ ハンドラのサンプル

ここでは、C++ でのアプリケーション開発について説明する。


ロビー クライアントとの通信

ロビー対象アプリケーションと関連するロビー クライアントのやり取りの大半は、間接的に行われる。アプリケーションがロビー クライアントに影響する何らかの処理を実行 (または逆にロビー クライアントがアプリケーションに影響する何らかの処理を実行) すると、Microsoft® DirectPlay® が適切なメッセージを送信する。たとえば、アプリケーションが接続の設定を変更すると、DirectPlay がロビー クライアントに通知し、新しい設定内容を提供する。ただし、ロビー クライアントに情報を直接提供するため、以下の 2 つのメソッドも用意されている。DirectPlay8LobbiedApplication.UpdateStatus および DirectPlay8LobbiedApplication.Send。

ゲームの状態に以下の変化のいずれかが発生したときには、ロビー クライアントに通知する必要がある。

  • セッションが接続された。
  • セッションが接続できない。
  • セッションが切断された。
  • セッションが終了した。
  • セッション ホストが移行した。
  • このコンピュータがセッション ホストになった。

ロビー クライアントにこれらの状態変化のいずれかを通知するには、DirectPlay8LobbiedApplication.UpdateStatus を呼び出し、lStatus パラメータを適切な値に設定する。DirectPlay は、ロビー クライアント メッセージ ハンドラの DirectPlay8LobbyEvent.SessionStatus メソッドを呼び出して、状態の変化を知らせる。

DirectPlay8LobbiedApplication.Send メソッドを使用すると、アプリケーションからロビー クライアントにメッセージを直接送信することができる。DirectPlay はロビー クライアントにデータをそのまま渡す。そのデータの処理は、ロビー クライアントが行わなければならない。

ロビー クライアントも、アプリケーションにデータを直接送信することができる。DirectPlay は、ロビー クライアント メッセージ ハンドラの DirectPlay8LobbyEvent.Receive メソッドを呼び出して、データを渡す。DirectPlay はアプリケーションにデータをそのまま渡す。ロビー クライアントは、このデータを処理しなければならない。


ロビー対象アプリケーションの終了

セッションを閉じるには、DirectPlay8LobbiedApplication.Close を呼び出す。Microsoft® DirectPlay® は、ロビー クライアント メッセージ ハンドラの DirectPlay8LobbyEvent.Disconnect メソッドを呼び出して、切断を知らせる。アプリケーションを引き続き実行し、別のセッションに接続するには、DirectPlay8LobbiedApplication.SetAppAvailable を呼び出して、アプリケーションが利用可能であることを示す。


Netmon を使った DirectPlay ネットワーク トラフィックの監視

ゲームの開発中 (特にバグを解析しているとき) には、Microsoft® DirectPlay® のネットワーク トラフィックを監視すると役立つことがある。ネットワーク モニタ (Netmon) は、ネットワーク トラフィックを分析するための標準ユーティリティである。DirectPlay メッセージングの 4 つのコンポーネント (サービス プロバイダ レイヤ、トランスポート レイヤ、セッション レイヤ、および音声レイヤ) を分析するため、DirectPlay には Netmon を使った一連のパーサーが用意されている。

  • Netmon と DirectPlay の連動
  • DirectPlay 向け Netmon の構成
  • DirectPlay ネットワーク トラフィックのキャプチャ
  • DirectPlay で Netmon を使用するためのヒント


Netmon と DirectPlay の連動

Microsoft® DirectPlay® のプロトコル スタックには、3 つの基本レイヤがある。

  • 音声レイヤとセッション レイヤは、スタックの最上位レベルを共有する。通常のメッセージングはセッション レイヤを通り、音声関連のメッセージングは音声レイヤを通る。
  • トランスポート レイヤは、スタックの中位にある。音声とセッションのトラフィックは、どちらもこのレイヤを通る。メッセージの分割と再構成や、消失したパケットの再転送などの作業は、このレイヤが担当する。
  • サービス プロバイダ レイヤは、スタックの一番下にある。すべてのメッセージングはこのレイヤで処理される。ネットワークとの通信は、このレイヤが担当する。たとえば、TCP/IP ネットワーキングの場合、サービス プロバイダは Winsock API を使ってネットワーク スタックと通信を行う。Netmon で解析できるネットワーク トラフィックは、IP または IPX サービス プロバイダ上を通るものに限られている。

DirectPlay パーサーをインストールすると、Netmon を使って、これら 4 つのレイヤのいずれかを通るネットワーク トラフィックを分析できる。サービス プロバイダ パーサーを選択すると、DirectPlay の全トラフィックを表示できる。また、上位レベルのパーサーのいずれかを選択すれば、興味のないトラフィックを除外することができる。

トランスポート レイヤ パーサーを使用すると、音声とセッションの全トラフィックが表示され、接続のためのハンドシェイクといった下位レベルのトラフィックは除外される。トランスポート レイヤでは、MTU (Maximum Transfer Unit) より長いメッセージが 1 つ以上の断片に分解されるので、注意すること。

セッション レイヤ パーサーと音声レイヤ パーサーを使用すると、セッション関連のトラフィックと音声関連のトラフィックを別々に分析できる。これらのパーサーは、どちらも分割を検知し、ユーザーに知らせるようになっているが、分割したパケットを分析することはできない。


DirectPlay 向け Netmon の構成

Windows 2000 Server システムを使用している場合、Netmon は既にインストールされている。Windows 2000 Professional の場合は、SMS (Systems Management Server) を購入する必要がある。Netmon の基本的な使い方については、Netmon のドキュメントを参照すること。Microsoft® DirectPlay® のトラフィックを監視するために Netmon を構成するには次の手順を実行する。

  1. 適切なフォルダに Dp8parser.dll をコピーする。Netmon のルート フォルダは、通常、\Winnt\System32 フォルダにインストールされる。SMS がインストールされている場合、ルート フォルダ名は NetMonFull となる。Windows 2000 Server の場合、ルート フォルダ名は NetMon となる。パーサー DLL を ...\NetMonFull\Parsers または ...\NetMon\parsers にコピーする。コピー先は、使用している Netmon のバージョンに依存する。
  2. Netmon を起動する。
  3. [キャプチャ] - [ネットワーク...] - [ローカル コンピュータ] で、キャプチャするアダプタを設定する。このとき、[ダイヤルアップ接続] プロパティがオフに設定されたアダプタを選択するように注意する。

これで、トラフィックのキャプチャを開始できる。


DirectPlay ネットワーク トラフィックのキャプチャ

キャプチャ処理を開始するには、[Microsoft ネットワーク モニタ] ツールバーの [キャプチャの開始] ボタンをクリックして、キャプチャ表示を開く。最初は、対象のアダプタを通るトラフィックがすべて表示される。この生のトラフィック ストリームは、興味のある一定のパケットだけに絞り込むことができる。Microsoft® DirectPlay® のパーサーをインストールすると、基本的に、DirectPlay 指向の 4 つのフィルタが Netmon に追加される。これらのフィルタを使用すると、キャプチャ表示から DirectPlay 以外のすべてのトラフィックを除外できる。

フィルタを選択するには次の手順を実行する。

  1. [Microsoft ネットワーク モニタ] ツールバーの [キャプチャ フィルタの編集] をクリックする。
  2. [Protocol == Any] をダブルクリックする。
  3. [全て無効] をクリックする。
  4. [無効なプロトコル] の [DPLAYSESSION]、[DPLAYSP]、[DPLAYTRANSPORT]、および [DPLAYVOICE] をダブルクリックする。

[OK] を 2 回クリックしてキャプチャ表示に戻る。これで、DirectPlay トラフィックの表示を開始できる。

キャプチャ表示でなく、キャプチャ処理自体にフィルタを適用することもできる。こうすると、たとえば、指定したポートから指定したポートへの IP パケットだけをキャプチャできる。詳細については、Netmon のドキュメントを参照すること。


DirectPlay で Netmon を使用するためのヒント

ここでは、Microsoft® DirectPlay® で Netmon を使用するためのヒントをいくつか紹介する。

  • デフォルトでは、最新のトラフィック 1 MB だけがキャプチャされるようになっている。この値は、10 ～ 20 MB 程度に増す必要があるかもしれない。
  • ハード ドライブへのストリームは行われないので、確認できるトラフィックは現在キャプチャ バッファ内にある内容に限られる。キャプチャ済みのトラフィックをハード ドライブにストリームするには、独自のキャプチャ処理を実装する必要がある。詳細については、MSDN を参照すること。
  • デフォルトでは、DirectPlay のパーサーは、[2302,2400]U{6073} ポート/ソケット範囲を使って、IP および IPX パケットをフィルタリングするようになっている。標準以外のポート/ソケット範囲を使用している場合には、ユーザー定義のポート/ソケット値をパーサーに認識させることができる。これには、\HKEY_CURRENT_USER\Software\Microsoft\DirectX\DirectPlay\Parsers レジストリ キーに、MinUserPort と MaxUserPort の 2 つの DWORD 値を追加する。この結果、ポート/ソケット範囲が [2302,2400]U{6073}U[MinUserPort,MaxUserPort] に拡張される。
  • DirectPlay プロトコルと RTP プロトコルは、どちらも UDP プロトコルの上位レイヤであるため、両者のパーサーが競合する可能性がある。したがって、DirectPlay トラフィックを分析するときは RTP パーサーを無効にし、RTP トラフィックを分析するときは DirectPlay パーサーを無効にしなければならない。


DirectPlay と DirectPlay Voice におけるコールバック関数の実装

ここでは、C++ でのアプリケーション開発について説明する。


クリティカル セクション オブジェクトを使った DirectPlay ネットワーキング コールバックの実装

Visual Basic では、マルチスレッド コールバックを使用しない。


DirectPlay DPNSVR アプリケーションの使い方

Microsoft Windows では、複数プロセス間で単独の IP ポートまたは IPX ポートを共有することができない。通信ホストとして機能するアプリケーションでは、それぞれ異なるポートを使用しなければならない。この制約により、特に実行中のゲームを列挙するといった作業を実行するときに、以下のようないくつかの問題が発生する。

  • ポートの競合を避ける。ほかのアプリケーションと競合しないポートを選択する必要がある。
  • 複数の通信ホストを単独システム上で管理する。ホストは、インスタンスごとに異なったポートを使用しなければならない。一方、クライアント アプリケーションは、特定のホストが使用しているポートを判断しなければならない。
  • 既に使用中のポートを避ける。望ましいポートが使用中の場合は、別のポートを使用できなければならない。

これらの問題に、DPNSVR アプリケーションは、列挙要求の転送サービスとして機能することによって対処する。アプリケーションは、ホストを開始するとき、動作中のポートを DPNSVR に知らせる。DPNSVR は、既知のポートで待機し、システム上のすべての Microsoft® DirectPlay® ホストに、すべての列挙要求を転送する。列挙要求への応答には、ホストが接続された実際のポートが含まれる。DPNSVR により、開発者は以下の利点が得られる。

  • 特定のシステムで実行されているゲームをすべて列挙する汎用列挙ルーチンを作成できる。
  • DirectPlay を使ってホストのポートを選択できる。クライアント アプリケーションが、DPNSVR のサービスを使って既知のポートで実行中のゲームを列挙すると、ホストが接続された実際のポートを含む応答が得られる。
  • アプリケーションが要求したポートを取得できない場合を、考慮する必要がない。
  • システム上にあるほかのアプリケーションとの競合について、心配する必要がない。

多くのアプリケーションでは DPNSVR のサービスを使用するが、DPNSVR を無効にしなければならない場合もある。その例を 2 つ示す。

  • 使用すべきポートを知っているが、コンピュータ上でそのアプリケーションのインスタンスが 1 つしか実行されない場合。
  • プレーヤーがセッションを列挙する能力を制限したい場合。DPNSVR を無効にすれば、ホストが接続されたポートを知っているプレーヤーだけが、ホストを列挙できる。

詳細については、｢DPNSVR の使い方｣を参照すること。


DPNSVR の使い方

対象のサービス プロバイダが DPNSVR をサポートしているかどうかを判断するには、DirectPlay8Peer、DirectPlay8Client、または DirectPlay8Server でサポートされる GetSPCaps メソッドを呼び出す。サービス プロバイダが DPNSVR をサポートしていれば、返される DPN_SP_CAPS 構造体の dwFlags メンバに DPNSPCAPS_SUPPORTSDPNSRV フラグが設定される。現時点では、IP および IPX サービス プロバイダだけが DPNSVR をサポートする。

DPNSVR はデフォルトで選択されているので、特別な操作をせずに使用できる。列挙要求をホストに転送したくない場合は、DPN_APPLICATION_DESC 型の dwFlags メンバに DPNSESSION_NODPNSVR フラグを設定して、DPNSVR を明示的に無効にする必要がある。

注 DPNSESSION_NODPNSVR フラグが設定されていても、動作中のポートを知っていれば、アプリケーションはいつでもホストを列挙することができる。


フォーカス キャプチャの実装

ここでは、C++ でのアプリケーション開発について説明する。


DirectPlay Visual Basic サンプル

以下のサンプル アプリケーションは、Visual Basic プログラミング言語用 Microsoft® DirectPlay® アプリケーション プログラミング インターフェイスの使い方および能力を示すものである。詳細については、個々のサンプル フォルダの Readme.txt ファイルを参照すること。サンプル フォルダは、すべて SDK ルート ディレクトリ (通常は C:\mssdk) の下にある。

  • Chat
  • Conferencer
  • DataRelay
  • DXVB Messenger
  • Memory
  • SimpleClient
  • SimplePeer
  • SimpleServer
  • SimpleVoice
  • StagedPeer
  • VoiceGroup


Chat

サンプル Chat は、SimplePeer に似た形をしている。プレーヤーがセッションのホストとなるか、またはセッションに接続すると、文字列の受け渡しによってプレーヤーどうしがチャットできるようになる。

パス

(SDK ルート)\Samples\Multimedia\VBSamples\DirectPlay\Chat


Conferencer

サンプル Conferencer は、Microsoft NetMeeting に似た形をしている。

パス

(SDK ルート)\Samples\Multimedia\VBSamples\DirectPlay\Conferencer


DataRelay

サンプル DataRelay は、SimplePeer と似ている。ただし、ダイアログ ボックスの UI で指定されたオプションが付いたデータ パケットを送信するようになっている。

パス

(SDK ルート)\Samples\Multimedia\VBSamples\DirectPlay\DataRelay


DXVB Messenger

サンプル DXVBMessenger は、インスタント メッセージングのための簡単なクライアント/サーバー アプリケーションである。

パス

(SDK ルート)\Samples\Multimedia\VBSamples\DirectPlay\DXVBMessenger


Memory

Memory は、"タイル" を合わせて高得点を目指す簡単なゲームである。

パス

(SDK ルート)\Samples\Multimedia\VBSamples\DirectPlay\Memory


SimpleClient

サンプル SimpleClient は、サーバーに接続し、サーバー上のほかのプレーヤーにおかしな顔をすることができる簡単なアプリケーションである。

パス

(SDK ルート)\Samples\Multimedia\VBSamples\DirectPlay\SimpleClient


SimplePeer

サンプル SimplePeer を使用すると、プレーヤーがおかしな顔をすることができる。プレーヤーは、ピアであってもセッション ホストであってもよい。

パス

(SDK ルート)\Samples\Multimedia\VBSamples\DirectPlay\SimplePeer


SimpleServer

サンプル SimpleServer は、接続してクライアント メッセージを転送できる簡単なサーバー アプリケーションである。

パス

(SDK ルート)\Samples\Multimedia\VBSamples\DirectPlay\SimpleServer


SimpleVoice

サンプル SimpleVoice は、SimplePeer に似た形をしている。プレーヤーがセッションのホストとなるか、またはセッションに接続すると、プレーヤーどうしがチャットできるようになる。

パス

(SDK ルート)\Samples\Multimedia\VBSamples\DirectPlay\SimpleVoice


StagedPeer

サンプル StagedPeer は、セッションへの参加またはセッションの作成に必要な接続設定をユーザーに促す 2 つのダイアログ ボックスと、プレーヤーを接続する。ユーザーがセッションに接続すると、同じセッションに接続された全プレーヤーがチャットできるマルチプレーヤー ステージが表示される。全員の準備が整い、ホストが開始を決定すると、プレーヤーが新しいゲームを開始できる。ホストは、プレーヤーを拒否したり、プレーヤーのスロットを閉じたりすることができる。

パス

(SDK ルート)\Samples\Multimedia\VBSamples\DirectPlay\StagedPeer


VoiceGroup

サンプル VoiceGroup は、SimpleVoice に似た形をしている。プレーヤーがセッションのホストとなるか、またはセッションに接続すると、プレーヤーどうしがチャットできるようになる。

パス

(SDK ルート)\Samples\Multimedia\VBSamples\DirectPlay\VoiceGroup


DirectPlay Visual Basic リファレンス

ここでは、Microsoft® DirectPlay® for Microsoft® Visual Basic® の API 要素に関するリファレンス情報を示す。リファレンス情報は、以下のカテゴリに分類される。

  • クラス
  • 関数
  • 型
  • 列挙
  • エラー コード


クラス

ここでは、以下の Microsoft® DirectPlay® クラスのメソッドに関するリファレンス情報を提供する。

  • DirectPlay8Address
  • DirectPlay8Client
  • DirectPlay8Event
  • DirectPlay8LobbiedApplication
  • DirectPlay8LobbyClient
  • DirectPlay8LobbyEvent
  • DirectPlay8Peer
  • DirectPlay8Server
  • DirectPlayVoiceClient8
  • DirectPlayVoiceEvent8
  • DirectPlayVoiceServer8
  • DirectPlayVoiceTest8


DirectPlay8Address

DirectPlay8Address クラスは、DirectPlay アドレスの作成と管理を行うメソッドを提供する。

DirectPlay8Address クラスのメソッドを次に示す。

DirectPlay8Address メソッド | AddComponentLong
 | AddComponentString
 | BuildFromURL
 | Clear
 | Duplicate
 | GetComponentLong
 | GetComponentString
 | GetDevice
 | GetNumComponents
 | GetSP
 | GetURL
 | GetUserData
 | SetDevice
 | SetEqual
 | SetSP
 | SetUserData


DirectPlay8Address.AddComponentLong

長整数型 (Long) のコンポーネントをアドレスに追加する。コンポーネントがアドレスの一部である場合、この呼び出しにより新しい値に置き換わる。

AddComponentLong(sComponent As String, lValue As Long)

指定項目

sComponent
コンポーネントのキーを保持する文字列。
lValue
コンポーネントに追加する長整数型 (Long) の値。

エラー コード

失敗した場合は、Err.Number に次のいずれかの値が設定される。

DPNERR_INVALIDPARAM
DPNERR_NOTALLOWED


DirectPlay8Address.AddComponentString

文字列型 (String) のコンポーネントをアドレスに追加する。コンポーネントがアドレスの一部である場合、この呼び出しにより新しい値に置き換わる。

AddComponentString(sComponent As String, sValue As String)

指定項目

sComponent
コンポーネントのキーを保持する文字列。
sValue
コンポーネントに追加する文字列型 (String) の値。

エラー コード

失敗した場合は、Err.Number に次のいずれかの値が設定される。

DPNERR_INVALIDPARAM
DPNERR_NOTALLOWED


DirectPlay8Address.BuildFromURL

オブジェクトを DirectPlay URL と等しいアドレスに設定する。オブジェクトの内容は消去される。

BuildFromURL(SourceURL As String)

指定項目

SourceURL
正しく整形された DirectPlay アドレスを保持する文字列。

エラー コード

失敗した場合は、Err.Number に次のいずれかの値が設定される。

DPNERR_INVALIDURL
DPNERR_NOTALLOWED


DirectPlay8Address.Clear

アドレス オブジェクトを空のアドレスにリセットする。

Clear()

エラー コード

失敗した場合は、Err.Number に次のいずれかの値が設定される。

DPNERR_NOTALLOWED


DirectPlay8Address.Duplicate

このオブジェクトのアドレスを複製する DirectPlay8Address オブジェクトを作成する。

Duplicate() As DirectPlay8Address

戻り値

DirectPlay8Address オブジェクトを返す。

エラー コード

失敗した場合は、Err.Number に次のいずれかの値が設定される。

DPNERR_GENERIC


DirectPlay8Address.GetComponentLong

整数型のコンポーネントの 1 つを、コンポーネントのアドレスの URL 文字列の形式で取得する。

GetComponentLong(sComponent As String) As Long

指定項目

sComponent
取得するコンポーネントの名前。

戻り値

要求されたコンポーネントの値を返す。

エラー コード

失敗した場合は、Err.Number に次のいずれかの値が設定される。

DPNERR_DOESNOTEXIST
DPNERR_INVALIDPARAM
DPNERR_BUFFERTOOSMALL

注意

URL 文字列の詳細については、「DirectPlay アドレシング」を参照すること。


DirectPlay8Address.GetComponentString

整数型のコンポーネントの 1 つを、コンポーネントのアドレスの URL 文字列の形式で取得する。

GetComponentString(sComponent As String) As String

指定項目

sComponent
取得するコンポーネントの名前。

戻り値

要求された文字列を返す。

エラー コード

失敗した場合は、Err.Number に次のいずれかの値が設定される。

DPNERR_DOESNOTEXIST
DPNERR_INVALIDPARAM
DPNERR_BUFFERTOOSMALL

注意

URL 文字列の詳細については、「DirectPlay アドレシング」を参照すること。


DirectPlay8Address.GetDevice

アドレス オブジェクトのローカル デバイス GUID を取得する。デバイスが指定されていない場合、このメソッドは DPNERR_DOESNOTEXIST を返す。

GetDevice() As String

戻り値

アドレス オブジェクトのデバイスを表す文字列型 (String) の値を返す。

エラー コード

失敗した場合は、Err.Number に次のいずれかの値が設定される。

DPNERR_DOESNOTEXIST


DirectPlay8Address.GetNumComponents

アドレスのコンポーネント数を取得する。

GetNumComponents() As Long

戻り値

このアドレス オブジェクトのコンポーネント数を返す。

エラー コード

失敗した場合は、Err.Number に次のいずれかの値が設定される。

DPNERR_INVALIDPARAM


DirectPlay8Address.GetSP

アドレス オブジェクトのサービス プロバイダ GUID を取得する。サービス プロバイダが指定されていない場合、このメソッドは DPNERR_DOESNOTEXIST を返す。

GetSP() As String

戻り値

アドレス オブジェクトのサービス プロバイダを返す。

エラー コード

失敗した場合は、Err.Number に次のいずれかの値が設定される。

DPNERR_DOESNOTEXIST


DirectPlay8Address.GetURL

このオブジェクトが表す DirectPlay アドレスの URL を取得する。

GetURL() As String

戻り値

このオブジェクトで表される URL を返す。

エラー コード

失敗した場合は、Err.Number に次のいずれかの値が設定される。

DPNERR_OUTOFMEMORY
DPNERR_INVALIDURL
DPNERR_GENERIC


DirectPlay8Address.GetUserData

アドレス オブジェクトのユーザー データを取得する。このアドレス オブジェクトにユーザー データがない場合、DPNERR_DOESNOTEXIST が返される。

GetUserData(UserData As Long)

指定項目

UserData
このアドレスからのユーザー データ。

エラー コード

失敗した場合は、Err.Number に次のいずれかの値が設定される。

DPNERR_DOESNOTEXIST


DirectPlay8Address.SetDevice

アドレス オブジェクトのローカル デバイス GUID を設定する。このアドレスにローカル デバイスが指定されている場合、上書きされる。

SetDevice(guidDevice As String)

指定項目

guidDevice
ローカル デバイスの GUID。

エラー コード

失敗した場合は、Err.Number に次のいずれかの値が設定される。

DPNERR_NOTALLOWED


DirectPlay8Address.SetEqual

この DirectPlay8Address オブジェクトに指定のアドレスを設定する。

SetEqual(Address As DirectPlay8Address)

指定項目

Address
このオブジェクトに設定する DirectPlay8Address オブジェクト。

エラー コード

失敗した場合は、Err.Number に次のいずれかの値が設定される。

DPNERR_NOTALLOWED


DirectPlay8Address.SetSP

アドレス オブジェクトのサービス プロバイダ GUID を設定する。このアドレスにサービス プロバイダが指定されている場合、上書きされる。

SetSP(guidSP As String)

指定項目

guidSP
設定するサービス プロバイダ GUID。

エラー コード

失敗した場合は、Err.Number に次のいずれかの値が設定される。

DPNERR_NOTALLOWED


DirectPlay8Address.SetUserData

アドレス オブジェクトのユーザー データを設定する。このアドレスにユーザー データがある場合、上書きされる。

SetUserData(UserData As Long, lDataSize As Long)

指定項目

UserData
アドレスのユーザー データ セクションに置かれるデータ。ユーザー データを消去するには、0 に設定する。
lDataSize
UserData のデータのサイズ (バイト単位)。UserData を 0 に設定した場合、この値も 0 に設定する必要がある。

エラー コード

失敗した場合は、Err.Number に次のいずれかの値が設定される。

DPNERR_NOTALLOWED


DirectPlay8Client

アプリケーションは、DirectPlay8Client クラスのメソッドを使用して、クライアント/サーバー セッション用のクライアント アプリケーションの作成と管理を行う。

DirectPlay8Client クラスのメソッドは、以下のグループにまとめることができる。

セッション管理 | Close
 | Connect
 | EnumHosts
 | GetApplicationDesc
 | GetCaps
 | GetCountServiceProviders
 | GetServiceProvider
 | GetSPCaps
 | SetCaps
 | SetSPCaps
メッセージ管理 | GetSendQueueInfo
 | RegisterMessageHandler
 | UnRegisterMessageHandler
 | Send
クライアント情報 | SetClientInfo
サーバー情報 | GetServerAddress
 | GetServerInfo
その他 | CancelAsyncOperation
 | GetConnectionInfo
 | RegisterLobby


DirectPlay8Client.CancelAsyncOperation

非同期要求を取り消す。デフォルトでは、DirectPlay8Client クラスの多くのメソッドが非同期に実行される。状況に応じて、要求が処理される前にその要求を取り消したい場合もある。このクラスで非同期に実行できるすべてのメソッドは、lAsyncHandle パラメータを返す。

このメソッドの lAsyncHandle パラメータに要求の lAsyncHandle を渡すことによって、特定の要求が取り消される。このメソッドを呼び出し、hAsyncHandle パラメータに 0 を、lFlags パラメータに DPNCANCEL_ALL_OPERATIONS を指定することによって、待機中のすべての非同期処理を取り消すことができる。特定のハンドルがこのメソッドに指定された場合は、lFlags パラメータに 0 を渡す必要がある。

CancelAsyncOperation(lAsyncHandle As Long, _
    [lFlags As CONST_DPNCANCELFLAGS])

指定項目

lAsyncHandle
停止する非同期処理のハンドル。この値を 0 に設定して、すべての要求または特定の種類の非同期要求を停止することができる。取り消す要求の特定のハンドルが指定された場合、lFlags パラメータは 0 にする必要がある。
lFlags
取り消す非同期要求を指定するフラグ。このフラグに CONST_DPNCANCELFLAGS 列挙のいずれかのフラグを設定できる。

エラー コード

失敗した場合は、Err.Number に次のいずれかの値が設定される。

DPNERR_PENDING
DPNERR_INVALIDFLAGS
DPNERR_CANNOTCANCEL
DPNERR_INVALIDHANDLE

注意

DirectPlay8Client.Send メソッドから返されたハンドルを指定すると、送信を取り消すことができる。DirectPlay8Event.SendComplete メソッドは、メッセージが DPNSEND_NOCOMPLETE フラグを設定して送信された場合を除き、その後も呼び出される。DirectPlay8Peer.CancelAsyncOperation を呼び出して送信処理を取り消した場合、DirectPlay8Event.SendComplete メソッドに渡された DPNMSG_SEND_COMPLETE 型の hResultCode メンバに、DPNERR_CANCELLED が設定される。


DirectPlay8Client.Close

セッションにより開いた接続を閉じる。

Close([lFlags As Long]);

指定項目

lFlags
予約済み。0 に設定すること。

エラー コード

失敗した場合は、Err.Number に次のいずれかの値が設定される。

DPNERR_UNINITIALIZED


DirectPlay8Client.Connect

サーバーへの接続を確立する。一度接続が確立すると、インターフェイス上の通信チャネルが開いてアクティブになり、アプリケーションはメッセージの到着を待機する。接続が完了するまで、DirectPlay8Client.Send メソッドを使用してメッセージを送信できない。

このメソッドを呼び出す前に、DirectPlay8Client.EnumHosts を呼び出してアプリケーションの記述を取得することができる。EnumHosts メソッドは、ホストされているアプリケーションごとに DPN_APPLICATION_DESC 型を返す。型は、アプリケーションの GUID など、アプリケーションを記述する。

ホストへの接続が要求された場合は、ホストのメッセージ ハンドラに DirectPlay8Event.IndicateConnect メソッドが呼び出される。ホストは、この接続を許可または拒否することができる。どちらの場合も、ホストがアクションを実行すると、クライアント メッセージ ハンドラの DirectPlay8Event.ConnectComplete メソッドが呼び出されて、応答を送信する。

Connect(AppDesc As DPN_APPLICATION_DESC, _
    Address As DirectPlay8Address, _
    DeviceInfo As DirectPlay8Address, _
    lFlags As CONST_DPNOPERATIONS, _
    UserData As Any, _
    UserDataSize As Long) As Long

指定項目

AppDesc
アプリケーションを記述する DPN_APPLICATION_DESC 型。この型で設定する必要がある唯一のメンバは、guidApplication メンバである。このメソッドで使用されるのは、この型のメンバのうちの一部だけである。設定する必要があるメンバは、guidApplication だけである。また、guidInstance、pwszPassword、dwFlags、および dwSize を設定することもできる。
Address
ホストしているコンピュータへの接続に使用するアドレス情報を指定する DirectPlay8Address オプション オブジェクト。
DeviceInfo
サーバーとの接続に使用するネットワーク アダプタ (つまり、NIC やモデムなど) を指定する DirectPlay8Address オブジェクト。
lFlags
接続モードを記述する CONST_DPNOPERATIONS 列挙のフラグ。次のフラグを設定できる。
DPNOP_SYNC

接続要求を同期をとりながら処理する。このフラグを設定しても、DirectPlay8Event.ConnectComplete メソッドの呼び出しは生成されない。

UserData
アプリケーション固有のユーザー データ。
UserDataSize
UserData パラメータに保持されるデータのサイズ。

戻り値

この処理に対する非同期ハンドルを返す。これは、要求が非同期で処理される場合に、要求を取り消すために DirectPlay8Client.CancelAsyncOperation メソッドの lAsyncHandle パラメータで使用されるハンドルである。

エラー コード

失敗した場合は、Err.Number に次のいずれかの値が設定される。

DPNERR_NOCONNECTION
DPNERR_INVALIDPASSWORD
DPNERR_INVALIDFLAGS
DPNERR_INVALIDINTERFACE
DPNERR_INVALIDAPPLICATION
DPNERR_NOTHOST
DPNERR_SESSIONFULL
DPNERR_HOSTREJECTEDCONNECTION
DPNERR_INVALIDINSTANCE

注意

列挙は、接続中であれば複数同時に実行することができるが、1 つのオブジェクトで利用できるのは 1 つの接続だけである。1 つ以上のアプリケーションへの接続を確立するには、別のオブジェクトを作成しなければならない。つまり、1 つのオブジェクトで利用できるのは、1 つの実行アプリケーションだけである。ほかの接続が進行中に DirectPlay8Client.Connect を呼び出すと、エラーが返される。


DirectPlay8Client.EnumHosts

Microsoft® DirectPlay® ゲームをホストするアプリケーションを列挙する。列挙基準を満たすアプリケーションが見つかると、アプリケーションのメッセージ ハンドラに DirectPlay8Event.EnumHostsResponse メソッドが呼び出される。このメソッドは、見つかったアプリケーションを記述する DPN_APPLICATION_DESC 型を格納する DPNMSG_ENUM_HOSTS_RESPONSE メッセージ型を含む。

EnumHosts(ApplicationDesc As DPN_APPLICATION_DESC, _
    AddrHost As DirectPlay8Address, _
    DeviceInfo As DirectPlay8Address, _
    lRetryCount As Long, _
    lRetryInterval As Long, _
    lTimeOut As Long, _
    lFlags As  CONST_DPNOPERATIONS, _
    UserData As Any, _
    UserDataSize As Long) As Long

指定項目

ApplicationDesc
列挙するアプリケーション ホストを指定する DPN_APPLICATION_DESC 構造体。列挙への応答数を減らすため、次のフィールドを指定できる。
guidApplication
検索するアプリケーションの GUID。指定されない場合は、すべてが検索される。
Password
指定するパスワード。セキュア セッションではパスワードがないと応答しない。
AddrHost
アプリケーションをホストしているコンピュータのアドレスを指定する DirectPlay8Address オブジェクト。
DeviceInfo
列挙するサービス プロバイダおよび設定を指定する DirectPlay8Address オブジェクト。
lRetryCount
列挙データを送信する回数を指定する値。このパラメータを 0 に設定すると、デフォルト値を指定できる。この値に INFINITE を設定した場合、列挙は取り消されるまで続行される。
lRetryInterval
列挙を試みる間隔 (ミリ秒単位) を指定する値。このパラメータを 0 に設定すると、デフォルト値を使用できる。
lTimeOut
列挙を実行する時間 (ミリ秒単位)。0 が指定された場合は、デフォルト値が使用される。INFINITE が指定された場合、列挙は取り消されるまで続行される。
lEnumPeriod
再列挙する頻度を指定する値。0 が指定された場合は、デフォルト値が使用される。
lFlags
このメソッドが処理される方法を制御する CONST_DPNOPERATIONS 列挙のフラグ。このメソッドには、次のフラグを設定できる。
DPNOP_SYNC
メソッドを同期をとりながら処理する。
UserData
列挙要求からホストに送信されるデータ ブロック。ネットワーク タイプによってデータのサイズに制限があるが、最低でも 512 バイトはサポートされている。
UserDataSize
UserData パラメータのデータ サイズ。

戻り値

この処理に対する非同期ハンドルを返す。これは、要求が非同期で処理される場合に、要求を取り消すために DirectPlay8Client.CancelAsyncOperation メソッドの lAsyncHandle パラメータで使用されるハンドルである。

エラー コード

失敗した場合は、Err.Number に次のいずれかの値が設定される。

DPNERR_TIMEDOUT
DPNERR_INVALIDFLAGS
DPNERR_INVALIDPARAM

注意

列挙の処理にはさまざまな方法があるため、メディアに関して特に知識がない限り、アプリケーションでは lEnumPeriod を指定しないことを推奨する。


DirectPlay8Client.GetApplicationDesc

接続されたアプリケーションに関するアプリケーションの記述全体を取得する。

GetApplicationDesc([lFlags As Long]) _
    As DPN_APPLICATION_DESC

指定項目

lFlags
予約済み。0 に設定すること。

戻り値

アプリケーションを記述する DPN_APPLICATION_DESC 型を返す。

エラー コード

失敗した場合は、Err.Number に次のいずれかの値が設定される。

DPNERR_NOCONNECTION
DPNERR_INVALIDFLAGS
DPNERR_BUFFERTOOSMALL
DPNERR_INVALIDPARAM


DirectPlay8Client.GetCaps

現在のオブジェクトに対する DPN_CAPS 型を取得する。

GetCaps([lFlags As Long]) As DPN_CAPS

指定項目

lFlags
予約済み。0 に設定すること。

戻り値

セッション パラメータが格納された DPN_CAPS 型を返す。

エラー コード

失敗した場合は、Err.Number に次のいずれかの値が設定される。

DPNERR_INVALIDOBJECT
DPNERR_INVALIDPOINTER
DPNERR_INVALIDPARAM
DPNERR_UNINITIALIZED

注意

DirectPlay8Client.RegisterMessageHandler の呼び出しが成功した後に、このメソッドを呼び出す必要がある。


DirectPlay8Client.GetConnectionInfo

ローカル エンドポイントとサーバー間の接続に関する統計情報を取得する。

GetConnectionInfo([lFlags As Long]) As DPN_CONNECTION_INFO

指定項目

lFlags
予約済み。0 に設定すること。

戻り値

指定した接続に関する情報を取得する DPN_CONNECTION_INFO 型を返す。

エラー コード

失敗した場合は、Err.Number に次のいずれかの値が設定される。

DPNERR_INVALIDOBJECT
DPNERR_INVALIDPOINTER
DPNERR_INVALIDPARAM
DPNERR_UNINITIALIZED

注意

Connect の呼び出しが成功した後にのみ、このメソッドを呼び出すことができる。


DirectPlay8Client.GetCountServiceProviders

アプリケーションで利用できる登録済みサービス プロバイダの数を取得する。

GetCountServiceProviders([lFlags As Long]) As Long

指定項目

lFlags
予約済み。0 に設定すること。

戻り値

アプリケーションで利用できる登録済みサービス プロバイダの数を返す。

エラー コード

失敗した場合は、Err.Number に次のいずれかの値が設定される。

DPNERR_INVALIDOBJECT


DirectPlay8Client.GetSendQueueInfo

アプリケーションで送信キューのサイズを監視するために使用する。Microsoft® DirectPlay® では、受け取り側のコンピュータの処理速度よりも高速にメッセージを送信することはない。そのため、送信元のコンピュータが、送信先が受け取れる速さよりも高速にメッセージを送信した場合、メッセージは送信側のキューに蓄積される。アプリケーションにより、送信キューのサイズが大きすぎると登録された場合は、メッセージの送信レートを低下させる必要がある。

GetSendQueueInfo(lNumMsgs As Long, _
    lNumBytes As Long, _
    [lFlags As CONST_DPNGETSENDQUEUEINFO])

指定項目

lNumMsgs
現在キューに蓄積されているメッセージの数。
lNumBytes
現在キューに蓄積されているメッセージ データの総バイト数。
lFlags
特定の優先レベルを持つ送信キュー情報を取得するには、CONST_DPNGETSENDQUEUEINFO 値の 1 つをこのパラメータに設定する。組み合わされた送信キュー情報を取得するには、このフラグに 0 (ゼロ) を設定する。

エラー コード

失敗した場合は、Err.Number に次のいずれかの値が設定される。

DPNERR_INVALIDPARAM


DirectPlay8Client.GetServerAddress

セッションのサーバーのアドレスを取得する。

GetServerAddress([lFlags As Long]) As DirectPlay8Address

指定項目

lFlags
予約済み。0 に設定すること。

戻り値

サーバーのアドレスを指定する DirectPlay8Address オブジェクトを返す。

エラー コード

失敗した場合は、Err.Number に次のいずれかの値が設定される。

DPNERR_INVALIDOBJECT
DPNERR_INVALIDPOINTER
DPNERR_INVALIDPARAM
DPNERR_UNINITIALIZED


DirectPlay8Client.GetServerInfo

DirectPlay8Server.SetServerInfo メソッドの呼び出しによって設定されたサーバーのデータ セットを取得する。

GetServerInfo([lFlags As Long]) As DPN_PLAYER_INFO

指定項目

lFlags
サーバーの名前またはデータ セットのいずれをこのメソッドが返すべきかを指定するには、CONST_DPNINFO フラグの 1 つをこのパラメータに設定する。

戻り値

サーバーの名前またはデータ セットを保持する DPN_PLAYER_INFO 型を返す。

エラー コード

失敗した場合は、Err.Number に次のいずれかの値が設定される。

DPNERR_UNINITIALIZED


DirectPlay8Client.GetServiceProvider

指定されたサービス プロバイダに関する情報を取得する。このメソッドを呼び出す前に、DirectPlay8Client.GetCountServiceProviders メソッドを呼び出して、アプリケーションで利用可能な登録済みサービス プロバイダの数を取得する。

GetServiceProvider(lIndex As Long) As DPN_SERVICE_PROVIDER_INFO

指定項目

lIndex
特定のサービス プロバイダを指定するインデックス値。

戻り値

サービス プロバイダを記述する DPN_SERVICE_PROVIDER_INFO 型を返す。

エラー コード

失敗した場合は、Err.Number に次のいずれかの値が設定される。

DPNERR_INVALIDPARAM


DirectPlay8Client.GetSPCaps

指定されたサービス プロバイダの DPN_SP_CAPS 構造体を取得する。

GetSPCaps(guidSP As String, _
    [lFlags As Long]) As DPN_SP_CAPS

指定項目

guidSP
情報を取得するサービス プロバイダの GUID を指定する文字列。
lFlags
予約済み。0 に設定すること。

戻り値

指定したサービス プロバイダに関する情報を受け取る DPN_SP_CAPS 型を返す。

エラー コード

失敗した場合は、Err.Number に次のいずれかの値が設定される。

DPNERR_INVALIDOBJECT
DPNERR_INVALIDPOINTER
DPNERR_INVALIDPARAM
DPNERR_UNINITIALIZED

注意

DirectPlay8Client.RegisterMessageHandler の呼び出しが成功した後に、このメソッドを呼び出す必要がある。


DirectPlay8Client.RegisterLobby

ロビーへのアプリケーションの登録または登録の解除を行う。

RegisterLobby(dpnHandle As Long, _
    LobbyApp As DirectPlay8LobbiedApplication, _
    [lFlags As Long])

指定項目

dpnHandle
DirectPlay8LobbiedApplication.UpdateStatus への呼び出しを行うときに使用する接続ハンドル。
LobbyApp
アプリケーションを指定する DirectPlay8LobbiedApplication オブジェクト。
lFlags
アプリケーションの登録または登録の解除を指定するには、2 つある CONST_DPNLOBBY 列挙値のうちの 1 つをこのパラメータに設定する。

エラー コード

失敗した場合は、Err.Number に次のいずれかの値が設定される。

DPNERR_INVALIDPARAM

注意

アプリケーションがロビーに登録されると、ロビー クライアントはゲーム ステータス内の変更通知を自動的に受け取る。


DirectPlay8Client.RegisterMessageHandler

DirectPlay8Client オブジェクトおよびサーバーからメッセージを受信する、クライアントのコード内のエントリ ポイントを登録する。このメソッドを呼び出してから、このクラスのその他のメソッドを呼び出す必要がある。

RegisterMessageHandler(event As DirectPlay8Event)

指定項目

event
クライアントおよびサーバーによって生成されたメッセージを受け取る DirectPlay8Event オブジェクト。

エラー コード

失敗した場合は、Err.Number に次のいずれかの値が設定される。

DPNERR_ALREADYREGISTERED

注意

新しいメッセージ ハンドラを登録する場合、まず DirectPlay8Client.UnRegisterMessageHandler を呼び出して、現在のメッセージ ハンドラの登録を解除する必要がある。


DirectPlay8Client.Send

サーバーにデータを送信する。メッセージは同期または非同期で送信することができる。

Send(buffer() As BYTE, _
    lTimeOut As Long, _
    [lFlags As CONST_DPNSENDFLAGS]) As Long

指定項目

buffer()
送信するデータを記述する BYTE 型の配列。
lTimeOut
メッセージの送信を待つ時間 (ミリ秒単位)。メッセージが lTimeOut 値で送信されていない場合、メッセージは送信されない。メッセージの送信に対してタイム アウトが必要でない場合は、このパラメータを 0 に設定する。
lFlags
送信動作を記述するフラグ。CONST_DPNSENDFLAGS 列挙で定義された次の 1 つ以上のフラグを設定できる。

戻り値

この処理に対する非同期ハンドルを返す。これは、要求が非同期で処理される場合に、要求を取り消すために DirectPlay8Client.CancelAsyncOperation メソッドの lAsyncHandle パラメータで使用されるハンドルである。

エラー コード

失敗した場合は、Err.Number に次のいずれかの値が設定される。

DPNERR_INVALIDFLAGS
DPNERR_TIMEDOUT

注意

このメソッドは、サーバーのメッセージ ハンドラで DirectPlay8Event.Receive メソッドを呼び出す。Send 要求が完了すると、クライアントのメッセージ ハンドラで DirectPlay8Event.SendComplete メソッドが呼び出される。SendComplete メソッドは、DPNMSG_SEND_COMPLETE メッセージ型を保持する。要求が成功したか失敗したかは、このメッセージ型の hResultCode メンバに保持される。アプリケーションは IDirectPlay8Client、IDirectPlay8Server、または IDirectPlay8Peer で Close を呼び出す前や最終リリースをする前に、CancelAsyncOperation を呼び出して残っている Send をキャンセルすべきである。それに失敗すると予期せぬ結果が起きる。


DirectPlay8Client.SetCaps

セッションの能力を設定する。

SetCaps(caps As DPN_CAPS, _
    [lFlags As Long])

指定項目

caps
現在のセッションに関する設定に使用される DPN_CAPS 型。
lFlags
予約済み。0 に設定すること。

エラー コード

失敗した場合は、Err.Number に次のいずれかの値が設定される。

DPNERR_INVALIDOBJECT
DPNERR_INVALIDPOINTER
DPNERR_INVALIDPARAM
DPNERR_UNINITIALIZED

注意

DirectPlay8Client.RegisterMessageHandler の呼び出しが成功した後に、このメソッドを呼び出す必要がある。


DirectPlay8Client.SetClientInfo

アプリケーションとのクライアントの静的設定を設定する。アプリケーションに基本的なプレーヤー情報を転送するには、接続前にこのメソッドを呼び出す。クライアントが正しくアプリケーションに接続すると、サーバーはこのメソッドで取得された情報を DirectPlay8Server.GetClientInfo メソッドを呼び出して取得できる。

SetClientInfo(PlayerInfo As DPN_PLAYER_INFO, _
    [lFlags As CONST_DPNOPERATIONS]) As Long

指定項目

PlayerInfo
設定するピア情報を保持する DPN_PLAYER_INFO 型。
lFlags
このメソッドが同期をとりながら処理できるようにするには、CONST_DPNOPERATIONS 列挙の DPNSETCLIENTINFO_SYNC フラグを設定する。

戻り値

この処理に対する非同期ハンドルを返す。これは、要求が非同期で処理される場合に、要求を取り消すために DirectPlay8Client.CancelAsyncOperation メソッドの lAsyncHandle パラメータで使用されるハンドルである。

エラー コード

失敗した場合は、Err.Number に次のいずれかの値が設定される。

DPNERR_NOCONNECTION
DPNERR_INVALIDFLAGS
DPNERR_INVALIDPARAM

注意

DirectPlay8Client.SetClientInfo メソッドを使用すると処理に負担がかかるため、非静的情報は DirectPlay8Client.Send メソッドを使用して転送すること。

アプリケーションへの接続後、このメソッドを使用してクライアント情報を変更できる。接続後にこのメソッドを呼び出すと、サーバーのメッセージ ハンドラで DirectPlay8Event.InfoNotify メソッドが呼び出される。


DirectPlay8Client.SetSPCaps

指定されたサービス プロバイダの能力を設定する。

SetSPCaps(guidSP As String, _
    spCaps As DPN_SP_CAPS, _
    [lFlags As Long])

指定項目

guidSP
情報を設定するサービス プロバイダの GUID を指定する文字列。
spCaps
指定したサービス プロバイダに関する情報を設定する DPN_SP_CAPS 型。
lFlags
予約済み。0 に設定すること。

エラー コード

失敗した場合は、Err.Number に次のいずれかの値が設定される。

DPNERR_INVALIDOBJECT
DPNERR_INVALIDPOINTER
DPNERR_INVALIDPARAM
DPNERR_UNINITIALIZED

注意

DirectPlay8Client.RegisterMessageHandler の呼び出しが成功した後に、このメソッドを呼び出す必要がある。


DirectPlay8Client.UnregisterMessageHandler

現在の DirectPlay8Client メッセージ ハンドラの登録を解除する。

UnRegisterMessageHandler()

注意

新しいメッセージ ハンドラを登録するには、その前にこのメソッドを呼び出す必要がある。


DirectPlay8Event

アプリケーションは、DirectPlay8Event クラスのメソッドを使用して、DirectPlay8Peer、DirectPlay8Client、および DirectPlay8Server の各クラスで生成される Microsoft® DirectPlay® イベントをキャプチャする。

DirectPlay8Peer オブジェクト、DirectPlay8Client オブジェクト、および DirectPlay8Server オブジェクトの RegisterMessageHandler を呼び出すと、DirectPlay8Event はそれぞれのオブジェクトに関連付けられる。

注 DirectPlay8Event オブジェクトを実装する場合、Microsoft® Visual Basic® のフォームにこのオブジェクトのすべてのメソッドを実装する必要がある。

DirectPlay8Event クラスのメソッドを次に示す。

DirectPlay8Event メソッド | AddRemovePlayerGroup
 | AppDesc
 | AsyncOpComplete
 | ConnectComplete
 | CreateGroup
 | CreatePlayer
 | DestroyGroup
 | DestroyPlayer
 | EnumHostsQuery
 | EnumHostsResponse
 | HostMigrate
 | IndicateConnect
 | IndicateConnectAborted
 | InfoNotify
 | Receive
 | SendComplete
 | TerminateSession


DirectPlay8Event.AddRemovePlayerGroup

プレーヤーまたはグループがグループに追加またはグループから削除されると、関連付けられた DirectPlay8Peer オブジェクト、DirectPlay8Client オブジェクト、または DirectPlay8Server オブジェクトによって呼び出される。

AddRemovePlayerGroup( _
    lMsgID As Long, _
    lPlayerID As Long, _
    lGroupID As Long, _
    fRejectMsg As Boolean)

指定項目

lMsgID
プレーヤーまたはグループがセッションに参加するかセッションから離れることを示す、次のいずれかのフラグ。
DPN_MSGID_ADD_PLAYER_TO_GROUP
プレーヤーがグループに参加した。
DPN_MSGID_REMOVE_PLAYER_FROM_GROUP
プレーヤーがグループから離れた。
lPlayerID
追加または削除されるプレーヤーまたはグループの ID が設定されるLong 値。
lGroupID
このプレーヤーまたはグループが追加または削除されるグループの ID が設定される Long 値。
fRejectMsg
パラメータはこのリリースではサポートされていない。


DirectPlay8Event.AppDesc

DirectPlay8Peer.SetApplicationDesc メソッドまたは DirectPlay8Server.SetApplicationDesc メソッドを呼び出してアプリケーションの記述が変更されると、呼び出される。

AppDesc(fRejectMsg As Boolean)

指定項目

fRejectMsg
パラメータはこのリリースではサポートされていない。


DirectPlay8Event.AsyncOpComplete

非同期処理が完了すると呼び出される。

AsyncOpComplete( _
    dpnotify As DPNMSG_ASYNC_OP_COMPLETE, _
    fRejectMsg As Boolean)

指定項目

dpnotify
非同期処理のハンドルと結果を保持する DPNMSG_ASYNC_OP_COMPLETE メッセージ型。
fRejectMsg
パラメータはこのリリースではサポートされていない。


DirectPlay8Event.ConnectComplete

ホストまたはサーバーへの接続が完了すると呼び出される。

ConnectComplete( _
    dpnotify As DPNMSG_CONNECT_COMPLETE,
    fRejectMsg As Boolean)

指定項目

dpnotify
接続の非同期ハンドルと結果を保持する DPNMSG_CONNECT_COMPLETE メッセージ型。
fRejectMsg
パラメータはこのリリースではサポートされていない。


DirectPlay8Event.CreateGroup

グループが作成されるときに呼び出される。

CreateGroup ( _
    lGroupID As Long, _
    lOwnerID As Long, _
    fRejectMsg As Boolean)

指定項目

lGroupID
グループの ID が設定される Long 値。
lOwnerID
所有者の ID が設定される Long 値。
fRejectMsg
パラメータはこのリリースではサポートされていない。


DirectPlay8Event.CreatePlayer

プレーヤーが作成されるときに呼び出される。

CreatePlayer ( _
    lPlayerID As Long, _
    fRejectMsg As Boolean)

指定項目

lPlayerID
プレーヤーの ID が設定される Long 値。
fRejectMsg
パラメータはこのリリースではサポートされていない。


DirectPlay8Event.DestroyGroup

グループが破棄されるときに呼び出される。

DestroyGroup( _
    lGroupID As Long, _
    lReason As Long, _
    fRejectMsg As Boolean)

指定項目

lGroupID
グループの ID が設定される Long 値。
lReason
グループが破棄された理由を示す Long 値。
fRejectMsg
パラメータはこのリリースではサポートされていない。


DirectPlay8Event.DestroyPlayer

プレーヤーが破棄されるときに呼び出される。

DestroyPlayer( _
    lPlayerID As Long, _
    lReason As Long, _
    fRejectMsg As Boolean)

指定項目

lPlayerID
プレーヤーの ID が設定される Long 値。
lReason
グループが破棄された理由を示す Long 値。
fRejectMsg
パラメータはこのリリースではサポートされていない。


DirectPlay8Event.EnumHostsQuery

DirectPlay8Peer.EnumHosts メソッドまたは DirectPlay8Client.EnumHosts メソッドによりホストの列挙が要求されると、呼び出される

EnumHostsQuery( _
    dpnotify As DPNMSG_ENUM_HOSTS_QUERY, _
    fRejectMsg As Boolean)

指定項目

dpnotify
受信したデータを保持する DPNMSG_ENUM_HOSTS_QUERY メッセージ型。
fRejectMsg
このブール値を TRUE に設定すると、列挙の要求を拒否する。ただし、照会を拒否した場合、Microsoft® DirectPlay® がクライアントの DirectPlay8Event.EnumHostsResponse を呼び出さないため、クライアントにセッションのホストとして認識されない。


DirectPlay8Event.EnumHostsResponse

DirectPlay8Peer.EnumHosts メソッドまたは DirectPlay8Client.EnumHosts メソッドの呼び出しで取得されたホスト情報が保持される。

EnumHostsResponse( _
    dpnotify As DPNMSG_ENUM_HOSTS_RESPONSE, _
    fRejectMsg As Boolean)

指定項目

dpnotify
ホスト情報を保持する DPNMSG_ENUM_HOSTS_RESPONSE メッセージ型。
fRejectMsg
パラメータはこのリリースではサポートされていない。


DirectPlay8Event.HostMigrate

DirectPlay8Peer.Host メソッドまたは DirectPlay8Server.Host メソッドの呼び出しによりセッションでホストが変更されると、呼び出される。

HostMigrate(NewHostID As Long, _
    fRejectMsg As Boolean)

指定項目

NewHostID
新しいホストの ID が設定される長整数型 (Long) の値。
fRejectMsg
パラメータはこのリリースではサポートされていない。


DirectPlay8Event.IndicateConnect

プレーヤーがセッションへの接続を要求すると、ホストのメッセージハンドラで呼び出される。

IndicateConnect( _
    dpnotify As DPNMSG_INDICATE_CONNECT, _
    fRejectMsg As Boolean)

指定項目

dpnotify
DPNMSG_INDICATE_CONNECT メッセージ型。
fRejectMsg
このブール値を FALSE に設定するとプレーヤーはセッションに参加でき、TRUE に設定するとプレーヤーの要求が拒否される。

注意

このメソッドが返った後、セッション参加の要求に対する応答によって、プレーヤーの DirectPlay8Event.ConnectComplete メソッドが呼び出される。接続要求が成功した場合、DPNMSG_CONNECT_COMPLETE 型の hResultCode メンバが 0 に設定される。接続要求が拒否された場合、hResultCode にエラー コードが設定される。


DirectPlay8Event.IndicateConnectAborted

プレーヤーの接続がホスト上で示された後、セッションに追加される前に失われると、呼び出される。

IndicateConnectAborted( _
    fRejectMsg As Boolean)

指定項目

fRejectMsg
パラメータはこのリリースではサポートされていない。


DirectPlay8Event.InfoNotify

クライアント、サーバー、ピア、またはグループが更新されると、呼び出される。

InfoNotify(lMsgID As Long, _
    lNotifyID As Long, _
    fRejectMsg As Boolean)

指定項目

lMsgID
次の定数のいずれかに設定される。
DPN_MSGID_CLIENT_INFO
クライアント情報が変更された。
DPN_MSGID_GROUP_INFO
グループ情報が変更された。
DPN_MSGID_PEER_INFO
ピア情報が変更された。
DPN_MSGID_SERVER_INFO
サーバー情報が変更された。
lNotifyID
通知 ID。
fRejectMsg
パラメータはこのリリースではサポートされていない。


DirectPlay8Event.Receive

プレーヤーまたはホストからメッセージが受信されると、受信側のメッセージ ハンドラが呼び出される。

Receive( _
    dpnotify As DPNMSG_RECEIVE,
    fRejectMsg As Boolean)

指定項目

dpnotify
送信されたデータを保持する DPNMSG_RECEIVE メッセージ型。
fRejectMsg
パラメータはこのリリースではサポートされていない。


DirectPlay8Event.SendComplete

受信側でメッセージが受信されると、送信側のメッセージ ハンドラで呼び出される。

SendComplete( _
    dpnotify As DPNMSG_SEND_COMPLETE, _
    fRejectMsg As Boolean)

指定項目

dpnotify
メッセージ送信の結果とメッセージ送信にかかった時間を保持する DPNMSG_SEND_COMPLETE メッセージ型。
fRejectMsg
パラメータはこのリリースではサポートされていない。


DirectPlay8Event.TerminateSession

DirectPlay8Peer.TerminateSession が呼び出された後、各セッション プレーヤーのメッセージ ハンドラで呼び出される。

TerminateSession( _
dpnotify As DPNMSG_TERMINATE_SESSION, _
fRejectMsg As Boolean)

指定項目

dpnotify
メッセージ送信の結果を保持する DPNMSG_TERMINATE_SESSION メッセージ型。
fRejectMsg
パラメータはこのリリースではサポートされていない。

注意

ホストの移行が許可されるピアツーピア セッションでは、現在のホストが DirectPlay8Peer.Close を呼び出すか応答を停止すると、ホストが移行する。このイベントが発生すると、以下が実行される。

  • Microsoft® DirectPlay® は、他のすべてのプレーヤーに対して、各プレーヤーの DirectPlay8Event.DestroyPlayer を呼び出して、ホストがセッションを離れたことを通知する。
  • 次に、新しいホスト以外のプレーヤーに対して、各プレーヤーの DirectPlay8Event.HostMigrate メソッドを呼び出して通知する。

ホストの移行が発生しないようにするには、現在のホストは DirectPlay8Peer.TerminateSession を呼び出してセッションを終了しなければならない。ホストがこの方法でセッションを終了すると、以下が実行される。

  • DirectPlay は各プレーヤーの DirectPlay8Event.TerminateSession メソッドを呼び出す。関連付けられた DPNMSG_TERMINATE_SESSION 型の hResultCodeに、DPNERR_HOSTTERMINATEDSESSION が設定される。
  • 次に DirectPlay は、各プレーヤーに対して DirectPlay8Event.DestroyPlayer 呼び出しを生成する。

ホストの移行が許可されないピアツーピア ゲームでは、ホストが DirectPlay8Peer.Close を呼び出すか応答を停止すると、セッションは終了する。このイベントが発生すると、以下が実行される。

  • DirectPlay が各プレーヤーの DirectPlay8Event.TerminateSession メソッドを呼び出す。関連付けられた DPNMSG_TERMINATE_SESSION 型の hResultCode に、DPNERR_HOSTTERMINATEDSESSION が設定される。
  • 次に DirectPlay は、各プレーヤーに対して DirectPlay8Event.DestroyPlayer 呼び出しを生成する。

クライアント/サーバー ゲームでは、ホストが DirectPlay8Server.Close を呼び出すか応答を停止すると、セッションは終了する。このイベントが発生すると、以下が実行される。

  • DirectPlay は、各プレーヤーの DirectPlay8Event.TerminateSession メソッドを呼び出す。関連付けられた DPNMSG_TERMINATE_SESSION 型の hResultCode に、DPNERR_CONNECTIONLOST が設定される。
  • サーバーが、DirectPlay8Server.Close を呼び出して自らセッションから離れた場合、サーバー自体のプレーヤーを含むセッション内の各プレーヤーに対して、サーバーの DirectPlay8Event.DestroyPlayer メソッドが 1 回ずつ呼び出される。
  • 自ら離れた場合以外は、サーバーのプレーヤーを除き、各クライアントのプレーヤーに対してサーバーの DirectPlay8Event.DestroyPlayer メソッドが呼び出される。


DirectPlay8LobbiedApplication

DirectPlay8LobbiedApplication クラスは、ロビーをサポートするアプリケーションで使用する。このクラスを使用すると、アプリケーションがロビーで起動できるように、アプリケーションをシステムに登録できる。また、アプリケーションは、ユーザーを照会せずに、ゲームの起動に必要な接続情報を取得できる。最後に、ロビー アプリケーションはこのクラスを使用して、アプリケーションを起動したロビー クライアントにメッセージと通知を送信できる。

DirectPlay8LobbiedApplication クラスのメソッドを次に示す。

DirectPlay8LobbiedApplication メソッド | Close
 | GetConnectionSettings
 | RegisterMessageHandler
 | RegisterProgram
 | Send
 | SetAppAvailable
 | SetConnectionSettings
 | UnRegisterMessageHandler
 | UnRegisterProgram
 | UpdateStatus


DirectPlay8LobbiedApplication.Close

ロビー アプリケーションを削除する。

Close()

エラー コード

失敗した場合は、Err.Number に次のいずれかの値が設定される。

DPNERR_INVALIDOBJECT


DirectPlay8LobbiedApplication.GetConnectionSettings

指定された接続の設定を取得する。

GetConnectionSettings(LobbyClient As Long, lFlags As Long)

指定項目

LobbyClient
設定を取得する接続のハンドル。
lFlags
将来の使用に備えて予約されているので、0 に設定しておく。

エラー コード

失敗した場合は、Err.Number に次のいずれかの値が設定される。

DPNERR_INVALIDPARAM
DPNERR_BUFFERTOOSMALL
DPNERR_INVALIDOBJECT
DPNERR_INVALIDFLAGS


DirectPlay8LobbiedApplication.RegisterMessageHandler

ロビー アプリケーションの状態変更に関する通知を受け取り、ロビー クライアントからのメッセージを受け取る、メッセージ ハンドラ関数を登録する。

RegisterMessageHandler(lobbyEvent As DirectPlay8LobbyEvent)

指定項目

lobbyEvent
通知の受け取りに使用される DirectPlay8LobbyEvent オブジェクト。

エラー コード

失敗した場合は、Err.Number に次のいずれかの値が設定される。

DPNERR_ALREADYREGISTERED
DPNERR_INVALIDPARAM

注意

新しいメッセージ ハンドラを登録する場合、まず DirectPlay8LobbiedApplication.UnRegisterMessageHandler を呼び出して、現在のメッセージ ハンドラの登録を解除する必要がある。


DirectPlay8LobbiedApplication.RegisterProgram

ロビー アウェア アプリケーションを Microsoft® DirectPlay® に登録する。ロビーによる起動を可能にするには、アプリケーションを登録する必要がある。

RegisterProgram( _
    ProgramDesc As DPL_PROGRAM_DESC, _
    lFlags As Long)

指定項目

ProgramDesc
登録するロビー アウェア アプリケーションを記述する DPL_PROGRAM_DESC 型。
lFlags
予約済み。0 に設定すること。

エラー コード

失敗した場合は、Err.Number に次のいずれかの値が設定される。

DPNERR_INVALIDFLAGS
DPNERR_INVALIDPARAM

注意

アプリケーションは 1 回だけ登録すればよい。アプリケーションをアンインストールするとき、DirectPlay8LobbiedApplication.UnRegisterProgram メソッドを呼び出して登録を解除する必要がある。ロビー クライアントが、システムから削除されたアプリケーションを起動しようとすると、DirectPlay はそのアプリケーションの登録を自動的に解除する。

DirectX® 8.0 では、RegisterProgram を使用する必要がある。アプリケーション情報をレジストリに手動で設定することはできない。このクラスを使用しないと、アプリケーションは移植できず、DirectPlay の将来のバージョンと互換性がなくなる。


DirectPlay8LobbiedApplication.Send

ロビー アプリケーションからロビー クライアントにメッセージを送信する。

Send(Target As Long, _
    buffer() As Byte, _
    lBufferSize As Long, _
    lTimeOut As Long, _
    lFlags As Long)

指定項目

Target
メッセージを受信するロビー クライアントのハンドルを指定する長整数型 (Long) の値。
buffer()
メッセージ バッファを保持するバイト型 (BYTE) の変数。
lBufferSize
buffer() パラメータのメッセージ バッファのサイズ (バイト単位) を指定する長整数型 (Long) の値。この値は、1 バイト以上、64 KB 以下でなければならない。
lTimeOut
処理する Send 要求を待つ時間 (ミリ秒単位) を指定する長整数型 (Long) の値。
lFlags
予約済み。0 に設定すること。

エラー コード

失敗した場合は、Err.Number に次のいずれかの値が設定される。

DPNERR_INVALIDFLAGS
DPNERR_INVALIDPARAM
DPNERR_SENDTOOLARGE

注意

バッファ サイズが 64 KB より大きい場合、Err.Number に DPNERR_SENDTOOLARGE が設定される。バッファ サイズが 0 に設定された場合、Err.Number に DPNERR_INVALIDPARAM が設定される。


DirectPlay8LobbiedApplication.SetAppAvailable

ロビー クライアントが接続するアプリケーションを利用できるようにしたり、利用できないようにする。通常、ロビー アプリケーションがロビー クライアントにより起動したのではなく、独立して起動した場合、このメソッドが呼び出される。また、ゲームが終了し、ほかのゲームの開始時にロビー クライアントに接続するため、ロビー アプリケーションが必要な場合も、このメソッドを呼び出す。

SetAppAvailable(fAvailable As Boolean)

指定項目

fAvailable
ブール値。アプリケーションが利用できる場合は TRUE、利用できない場合は FALSE に設定する。

エラー コード

失敗した場合は、Err.Number に次のいずれかの値が設定される。

DPNERR_INVALIDOBJECT


DirectPlay8LobbiedApplication.SetConnectionSettings

接続の設定を指定する。

SetConnectionSettings(hTarget As Long, _
    lFlags As Long, _
    ConnectionSettings As DPL_CONNECTION_SETTINGS, _
    HostAddress As DirectPlay8Address, _
    Device As DirectPlay8Address)

指定項目

hTarget
接続ハンドルが設定される Long 型の値。
lFlags
将来の使用に備えて予約されているので、0 に設定しておく。
ConnectionSettings
接続設定を保持する DPL_CONNECTION_SETTINGS 型。
HostAddress
ホスト アドレスを保持する DirectPlay8Address オブジェクト。
Device
デバイス アドレスを保持する DirectPlay8Address オブジェクト。


DirectPlay8LobbiedApplication.UnRegisterMessageHandler

現在の DirectPlay8LobbiedApplication メッセージ ハンドラの登録を解除する。

UnRegisterMessageHandler()

注意

新しいメッセージ ハンドラを登録するには、その前にこのメソッドを呼び出す必要がある。


DirectPlay8LobbiedApplication.UnRegisterProgram

DirectPlay8LobbiedApplication.RegisterProgram メソッドにより登録されたロビー アウェア アプリケーションの登録を解除する。

UnRegisterProgram(guidApplication As String, lFlags As Long)

指定項目

guidApplication
登録を解除するアプリケーションの GUID。
lFlags
予約済み。0 に設定すること。

エラー コード

失敗した場合は、Err.Number に次のいずれかの値が設定される。

DPNERR_INVALIDPARAM


DirectPlay8LobbiedApplication.UpdateStatus

接続されたロビー クライアントの状態を更新する。

UpdateStatus(LobbyClient As Long, _
    lStatus As CONST_DPLSESSION)

指定項目

LobbyClient
ロビー クライアントの接続ハンドルを指定する Long 値。
lStatus
ロビー クライアントとロビー アプリケーション間の状態を指定する CONST_DPLSESSION 列挙の定数の 1 つ。

エラー コード

失敗した場合は、Err.Number に次のいずれかの値が設定される。

DPNERR_INVALIDPARAM

注意

DirectPlay8Client.RegisterLobby または DirectPlay8Peer.RegisterLobby を呼び出してロビーにアプリケーションを登録するときに、接続ハンドルを定義する。


DirectPlay8LobbyClient

DirectPlay8LobbyClient クラスは、ロビー クライアント アプリケーションで使用され、ローカル コンピュータでロビー対応ゲーム アプリケーションの列挙と起動を行う。また、実行中のゲーム アプリケーションとの通信にも使用する。ロビー クライアントは、ロビーおよびロビーされるゲーム アプリケーションからのメッセージを処理するため、メッセージ ハンドラ ルーチンを登録する必要がある。

DirectPlay8LobbyClient クラスのメソッドを次に示す。

DirectPlay8LobbyClient メソッド | Close
 | ConnectApplication
 | GetCountLocalPrograms
 | GetLocalProgram
 | RegisterMessageHandler
 | ReleaseApplication
 | Send
 | SetConnectionSettings
 | UnRegisterMessageHandler


DirectPlay8LobbyClient.Close

ロビー クライアントを削除する。

Close()

エラー コード

失敗した場合は、Err.Number に次のいずれかの値が設定される。

DPNERR_INVALIDOBJECT


DirectPlay8LobbyClient.ConnectApplication

DPL_CONNECT_INFO 型で指定されたセッションにロビー対応アプリケーションを接続する。アプリケーションが実行されていない場合、このメソッドを使用してアプリケーションを起動できる。

接続が正しく確立されると、Microsoft® DirectPlay® はメッセージ ハンドラの DirectPlay8LobbyEvent.Connect メソッドを呼び出す。

ConnectApplication( _
    ConnectionInfo As DPL_CONNECT_INFO,
    lTimeOut As Long, _
    lFlags As CONST_DPLCONNECT) As Long

指定項目

ConnectionInfo
接続先アプリケーションの GUID を含む、接続パラメータを記述する DPL_CONNECT_INFO 型。
lTimeOut
処理する接続を待つ時間 (ミリ秒単位) を指定する長整数型 (Long) の値。
lFlags
接続動作を決定する CONST_DPLCONNECT 列挙の定数の 1 つ。

戻り値

アプリケーション接続ハンドルが設定される Long 値を返す。このハンドルは、アプリケーションとの通信に使用される。また、このハンドルは DirectPlay8LobbyClient.ReleaseApplication メソッドの Application パラメータでも使用される。

エラー コード

失敗した場合は、Err.Number に次のいずれかの値が設定される。

DPNERR_CANTLAUNCHAPPLICATION
DPNERR_INVALIDFLAGS
DPNERR_INVALIDPARAM
DPNERR_TIMEDOUT


DirectPlay8LobbyClient.GetCountLocalPrograms

システムに登録されているロビー アプリケーションの数を取得する。

GetCountLocalPrograms(guidApplication As String) As Long

指定項目

guidApplication
列挙するロビー アプリケーションの GUID を指定する文字列型 (String) の値。

戻り値

登録されているロビー アプリケーションの数を返す。


DirectPlay8LobbyClient.GetLocalProgram

システムに登録されている指定されたロビー アプリケーションを列挙する。このメソッドを呼び出す前に、DirectPlay8LobbyClient.GetCountLocalPrograms を呼び出して登録されているロビー アプリケーションの数を調べる

GetLocalProgram(lProgID As Long) As DPL_APPLICATION_INFO

指定項目

lProgID
列挙するロビー アプリケーションの ID を指定する長整数型 (Long) の値。

戻り値

ロビー アプリケーションを記述する DPL_APPLICATION_INFO 構造体を返す。

エラー コード

失敗した場合は、Err.Number に次のいずれかの値が設定される。

DPNERR_INVALIDFLAGS
DPNERR_INVALIDPARAM

注意

通常、このメソッドは 2 回呼び出される。1 回目は、必要なバッファのサイズを取得するために呼び出される。2 回目は、正しいバッファ サイズを使用して呼び出される。


DirectPlay8LobbyClient.RegisterMessageHandler

ロビー クライアントの状態変更に関する通知を受け取り、ロビー アプリケーションからのメッセージを受け取る、メッセージ ハンドラ関数を登録する。

RegisterMessageHandler(lobbyEvent As DirectPlay8LobbyEvent)

指定項目

lobbyEvent
通知の受け取りに使用される DirectPlay8LobbyEvent オブジェクト。

エラー コード

失敗した場合は、Err.Number に次のいずれかの値が設定される。

DPNERR_ALREADYREGISTERED
DPNERR_INVALIDPARAM

注意

新しいメッセージ ハンドラを登録する場合、まず DirectPlay8LobbyClient.UnRegisterMessageHandler を呼び出して、現在のメッセージ ハンドラの登録を解除する必要がある。


DirectPlay8LobbyClient.ReleaseApplication

ロビー アプリケーションを解放し、ロビー クライアントとアプリケーション間の接続を閉じる。ロビー クライアントがアプリケーションとのセッションを終了するごとに、このメソッドを呼び出す必要がある。

ReleaseApplication(Application As Long)

指定項目

Application
解放するロビー アプリケーションの GUID を指定する長整数型 (Long) の値。この値は、DirectPlay8LobbyClient.ConnectApplication メソッドによって返される。

エラー コード

失敗した場合は、Err.Number に次のいずれかの値が設定される。

DPNERR_INVALIDHANDLE
DPNERR_INVALIDFLAGS
DPNERR_INVALIDPARAM


DirectPlay8LobbyClient.Send

このロビー クライアントにより起動されたか、このロビー クライアントにより接続されたロビー アプリケーションにメッセージを送信する。

Microsoft® DirectPlay® は、ターゲット メッセージ ハンドラの DirectPlay8LobbyEvent.Receive メソッドを呼び出して、ターゲットにデータを送信する。

Send(Target As Long, _
    buffer() As Byte, _
    lBufferSize As Long, _
    lFlags As Long)

指定項目

Target
メッセージ転送のターゲットを指定する長整数型 (Long) の値。
buffer()
メッセージを保持するバッファ。
lBufferSize
buffer() パラメータのメッセージ バッファのサイズ (バイト単位)。この値は、1 バイト以上、64 KB 以下でなければならない。
lFlags
予約済み。0 に設定すること。

エラー コード

失敗した場合は、Err.Number に次のいずれかの値が設定される。

DPNERR_INVALIDHANDLE
DPNERR_INVALIDFLAGS
DPNERR_INVALIDPARAM
DPNERR_SENDTOOLARGE

注意

バッファ サイズが 64 KB より大きい場合、Err.Number に DPNERR_SENDTOOLARGE が設定される。バッファ サイズが 0 に設定された場合、Err.Number に DPNERR_INVALIDPARAM が設定される。


DirectPlay8LobbyClient.SetConnectionSettings

指定された接続に関連付ける接続設定を設定する。

SetConnectionSettings(hTarget As Long, _
    lFlags As Long, _
    ConnectionSettings As DPL_CONNECTION_SETTINGS), _
    HostAddress As DirectPlay8Address, _
    Device As DirectPlay8Address)

指定項目

hTarget
接続ハンドルが設定される Long 型の値。
lFlags
予約済み。0 を設定しておく。
ConnectionSettings
接続を保持する DPL_CONNECTION_SETTINGS 構造体。
HostAddress
ホスト アドレスを保持する DirectPlay8Address オブジェクト。
Device
デバイス アドレスを保持する DirectPlay8Address オブジェクト。

エラー コード

失敗した場合は、Err.Number に次のいずれかの値が設定される。

DPNERR_INVALIDPARAM
DPNERR_INVALIDOBJECT
DPNERR_INVALIDFLAGS


DirectPlay8LobbyClient.UnRegisterMessageHandler

現在の DirectPlay8LobbyClient メッセージ ハンドラの登録を解除する。

UnRegisterMessageHandler()

注意

新しいメッセージ ハンドラを登録するには、その前にこのメソッドを呼び出す必要がある。


DirectPlay8LobbyEvent

DirectPlay8LobbyEvent クラスは、DirectPlay8LobbiedApplication クラスおよび DirectPlay8LobbyClient クラスの使用中に生成される Microsoft® DirectPlay® イベントをキャプチャするときに使用される。

注 DirectPlay8LobbyEvent オブジェクトを実装する場合、Microsoft® Visual Basic® のフォームにこのオブジェクトのすべてのメソッドを実装する必要がある。

DirectPlay8LobbyEvent クラスのメソッドを次に示す。

DirectPlay8LobbyEvent メソッド | Connect
 | ConnectionSettings
 | Disconnect
 | Receive
 | SessionStatus


DirectPlay8LobbyEvent.Connect

ロビー クライアントにより DirectPlay8LobbyClient.ConnectApplication メソッドが呼び出されると、呼び出される。

Connect( _
    dlNotify As DPL_MESSAGE_CONNECT, _
    fRejectMsg As Boolean)

指定項目

dlNotify
接続情報を保持する DPL_MESSAGE_CONNECT メッセージ型。
fRejectMsg
アプリケーションを接続するかどうかを示すブール値。


DirectPlay8LobbyEvent.ConnectionSettings

DirectPlay8LobbyClient.SetConnectionSettings メソッドまたは DirectPlay8LobbiedApplication.SetConnectionSettings メソッドが呼び出されると、呼び出される。

ConnectionSettings( _ConnectionSettings As DPL_MESSAGE_CONNECTION_SETTINGS)

指定項目

ConnectionSettings
接続設定を保持する DPL_MESSAGE_CONNECTION_SETTINGS メッセージ型。


DirectPlay8LobbyEvent.Disconnect

ロビー クライアントにより DirectPlay8LobbyClient.ReleaseApplication メソッドが呼び出されると、呼び出される。

Disconnect(DisconnectID As Long, _
    lReason As Long)

指定項目

DisconnectID
接続解除を要求したロビー アプリケーションの識別子を指定する長整数型 (Long) の値。
lReason
接続を解除する理由が設定される Long 値。


DirectPlay8LobbyEvent.Receive

DirectPlay8LobbyClient.Send メソッドまたは DirectPlay8LobbiedApplication.Send メソッドが呼び出されると、呼び出される。

Receive(dlNotify As DPL_MESSAGE_RECEIVE, _
     fRejectMsg As Boolean)

指定項目

dlNotify
送信されたメッセージを保持する DPL_MESSAGE_RECEIVE メッセージ型。
fRejectMsg
メッセージを受け取るか拒否するかを示すブール値。


DirectPlay8LobbyEvent.SessionStatus

ロビー アプリケーションにより DirectPlay8LobbiedApplication.UpdateStatus メソッドが呼び出されると、呼び出される。

LobbySessionStatus(status As Long, _
     lHandle As Long)

指定項目

status
ロビー セッションの更新された状態を指定する長整数型 (Long) の値。ロビー クライアントとロビー アプリケーション間の状態を指定する CONST_DPLSESSION 列挙の定数の 1 つが設定される。
lHandle
状態更新メッセージを送信したアプリケーションのハンドルが設定される Long 値。


DirectPlay8Peer

アプリケーションでは、DirectPlay8Peer クラスのメソッドを使用して、ピアツーピアの Microsoft® DirectPlay® セッションを作成する。

DirectPlay8Peer クラスのメソッドは、以下のグループにまとめることができる。

セッション管理 | Close
 | Connect
 | EnumHosts
 | GetApplicationDesc
 | GetCaps
 | GetConnectionInfo
 | GetCountServiceProviders
 | GetEnumHostResponseAddress
 | GetServiceProvider
 | GetSPCaps
 | Host
 | SetApplicationDesc
 | SetCaps
 | SetSPCaps
 | TerminateSession
メッセージ管理 | GetSendQueueInfo
 | RegisterMessageHandler
 | SendTo
 | UnregisterMessageHandler
プレーヤー管理 | DestroyPeer
 | GetPlayerOrGroup
 | GetCountClientsAndGroups
 | GetPeerAddress
 | GetPeerInfo
 | RemovePlayerFromGroup
 | SetPeerInfo
グループ管理 | AddPlayerToGroup
 | CreateGroup
 | DestroyGroup
 | GetCountGroupMembers
 | GetGroupInfo
 | GetGroupMember
 | SetGroupInfo
その他 | CancelAsyncOperation
 | RegisterLobby


DirectPlay8Peer.AddPlayerToGroup

グループにピアを追加する。

このメソッドが呼び出されると、DirectPlay は各プレーヤーの DirectPlay8Event.AddRemovePlayerGroup メソッドを呼び出して、プレーヤーに新しいグループ メンバを通知する。

AddPlayerToGroup(idGroup As Long, _
    idClient As Long,
    lFlags As Long) As Long

指定項目

idGroup
ピアを追加する先のグループの識別子を指定する長整数型 (Long) の値。
idClient
グループに追加されるピアの識別子を指定する長整数型 (Long) の値。
lFlags
このメソッドが処理される方法を制御するフラグ。このメソッドには、次のフラグを設定できる。
DPNOP_SYNC
メソッドを同期をとりながら処理する。

戻り値

この処理に対する非同期ハンドルを返す。これは、要求が非同期で処理される場合に、要求を取り消すために DirectPlay8Peer.CancelAsyncOperation メソッドの lAsyncHandle パラメータで使用されるハンドルである。

エラー コード

失敗した場合は、Err.Number に次のいずれかの値が設定される。

DPNERR_INVALIDGROUP
DPNERR_INVALIDFLAGS

注意

ピアはそれ自体またはほかのピアを既存のグループに追加できる。ピアがグループに正しく追加されると、グループに送信されるすべてのメッセージがそのピアにも送信される。

ピアがそれ自体をグループに追加する場合は、idClient パラメータに DPNID_ME を渡す。


DirectPlay8Peer.CancelAsyncOperation

非同期要求を取り消す。デフォルトでは、DirectPlay8Peer クラスの多くのメソッドが非同期に実行される。状況に応じて、要求が処理される前にその要求を取り消したい場合もある。このクラスで非同期に実行できるすべてのメソッドは、lAsyncHandle パラメータを返す。

このメソッドの lAsyncHandle パラメータに要求の lAsyncHandle を渡すことによって、特定の要求が取り消される。このメソッドを呼び出し、hAsyncHandle パラメータに 0 を、lFlags パラメータに DPNCANCEL_ALL_OPERATIONS を指定することによって、待機中のすべての非同期処理を取り消すことができる。特定のハンドルがこのメソッドに指定された場合は、lFlags パラメータに 0 を渡す必要がある。

CancelAsyncOperation(lAsyncHandle As Long, _
    lFlags As CONST_DPNCANCELFLAGS)

指定項目

lAsyncHandle
停止する非同期処理のハンドル。この値を 0 に設定して、すべての要求または特定の種類の非同期要求を停止することができる。取り消す要求の特定のハンドルが指定された場合、lFlags パラメータは 0 にする必要がある。
lFlags
取り消す非同期要求を指定するフラグ。このフラグに CONST_DPNCANCELFLAGS 列挙のいずれかのフラグを設定できる。

エラー コード

失敗した場合は、Err.Number に次のいずれかの値が設定される。

DPNERR_PENDING
DPNERR_INVALIDFLAGS
DPNERR_CANNOTCANCEL
DPNERR_INVALIDHANDLE

注意

DirectPlay8Peer.SendTo メソッドから返されたハンドルを指定すると、送信要求を取り消すことができる。DirectPlay8Event.SendComplete メソッドは、メッセージが DPNSEND_NOCOMPLETE フラグを設定して送信された場合を除き、その後も呼び出される。DirectPlay8Peer.CancelAsyncOperation を呼び出して送信処理を取り消した場合、DirectPlay8Event.SendComplete メソッドに渡された DPNMSG_SEND_COMPLETE 型の hResultCode メンバに、DPNERR_CANCELLED が設定される。


DirectPlay8Peer.Close

セッションにより開いた接続を閉じる。

Close();

エラー コード

失敗した場合は、Err.Number に次のいずれかの値が設定される。

DPNERR_UNINITIALIZED


DirectPlay8Peer.Connect

サーバーへの接続を確立する。一度接続が確立すると、オブジェクト上の通信チャネルが開いてアクティブになり、アプリケーションはメッセージの到着を待機する。接続が完了するまで、DirectPlay8Peer.SendTo メソッドを使用してメッセージを送信できない。

このメソッドを呼び出す前に、DirectPlay8Peer.EnumHosts を呼び出してアプリケーションの記述を取得する必要がある。EnumHosts メソッドは、ホストされているアプリケーションごとに DPN_APPLICATION_DESC 型を返す。型は、アプリケーションの GUID など、アプリケーションを記述する。

アプリケーションの GUID が必要ない場合でも、指定されれば Microsoft® DirectPlay® は確認を実行する。

ホストへの接続が要求された場合は、ホストのメッセージ ハンドラに DirectPlay8Event.IndicateConnect メソッドが呼び出される。ホストは、この接続を許可または拒否することができる。どちらの場合も、ホストがアクションを実行すると、クライアント メッセージ ハンドラの DirectPlay8Event.ConnectComplete メソッドが呼び出されて、応答を送信する。

Connect(AppDesc As DPN_APPLICATION_DESC, _
    Address As DirectPlay8Address, _
    DeviceInfo As DirectPlay8Address, _
    lFlags As Long, _
    UserData As Any, _
    UserDataSize As Long) As Long

指定項目

AppDesc
アプリケーションを記述する DPN_APPLICATION_DESC 型。このメソッドで使用されるのは、この型のメンバのうちの一部だけである。この型で設定する必要がある唯一のメンバは、guidApplication メンバである。guidInstance、Password、および lFlags も設定できる。
Address
ホストしているコンピュータへの接続に使用するアドレス情報を指定する DirectPlay8Address オプション オブジェクト。
DeviceInfo
列挙するサービス プロバイダおよび使用する設定を指定する DirectPlay8Address オブジェクト。
lFlags
接続モードを記述するフラグ。次のフラグを設定できる。
DPNOP_SYNC
接続要求を同期をとりながら処理する。このフラグが設定されている場合、DirectPlay は DirectPlay8Event.ConnectComplete メソッドを呼び出さない。
UserData
アプリケーション固有のユーザー データ。
UserDataSize
UserData パラメータに保持されるデータのサイズ。

戻り値

この処理に対する非同期ハンドルを返す。これは、要求が非同期で処理される場合に、要求を取り消すために DirectPlay8Peer.CancelAsyncOperation メソッドの lAsyncHandle パラメータで使用されるハンドルである。

エラー コード

失敗した場合は、Err.Number に次のいずれかの値が設定される。

DPNERR_NOCONNECTION
DPNERR_INVALIDPASSWORD
DPNERR_INVALIDFLAGS
DPNERR_INVALIDINTERFACE
DPNERR_INVALIDAPPLICATION
DPNERR_NOTHOST
DPNERR_SESSIONFULL
DPNERR_HOSTREJECTEDCONNECTION
DPNERR_INVALIDINSTANCE

注意

列挙は、接続中であれば複数同時に実行することができるが、1 つのオブジェクトで利用できるのは 1 つの接続だけである。1 つ以上のアプリケーションへの接続を確立するには、別のオブジェクトを作成しなければならない。つまり、1 つのオブジェクトで利用できるのは、1 つの実行アプリケーションだけである。ほかの接続を実行中に DirectPlay8Peer.Connect を呼び出すと、エラーが返される。


DirectPlay8Peer.CreateGroup

現在のセッション内でグループを作成する。グループはプレーヤーの論理的な集まりである。

このメソッドが呼び出されると、DirectPlay は各プレーヤーの DirectPlay8Event.CreateGroup メソッドを呼び出して、プレーヤーに新しいグループを通知する。

CreateGroup(GroupInfo As DPN_GROUP_INFO, _
    lFlags As Long) As Long

指定項目

GroupInfo
グループの記述を保持する DPN_GROUP_INFO 構造体。
lFlags
このメソッドが処理される方法を制御するフラグ。このメソッドには、次のフラグを設定できる。
DPNOP_SYNC
メソッドを同期をとりながら処理する。

戻り値

この処理に対する非同期ハンドルを返す。これは、要求が非同期で処理される場合に、要求を取り消すために DirectPlay8Peer.CancelAsyncOperation メソッドの lAsyncHandle パラメータで使用されるハンドルである。

エラー コード

失敗した場合は、Err.Number に次のいずれかの値が設定される。

DPNERR_INVALIDFLAGS

注意

Microsoft® DirectPlay® は、階層グループを保持しない。これは、これらのグループがフラット グループとグループ データの活用により簡単に実装できるためである。


DirectPlay8Peer.DestroyPeer

セッションからピアを削除する。

DestroyPeer(idClient As Long, _
    lFlags As Long, _
    UserData As Any, _
    UserDataSize As Long)

指定項目

idClient
削除するピアの識別子を指定する長整数型 (Long) の値。
lFlags
予約済み。0 に設定すること。
UserData
ピアに送信される追加削除データ情報を記述するポインタ。
UserDataSize
UserData パラメータに保持されるデータ サイズを指定する Long 値。

エラー コード

失敗した場合は、Err.Number に次のいずれかの値が設定される。

DPNERR_NOTHOST
DPNERR_INVALIDPLAYER
DPNERR_INVALIDPARAM

注意

このメソッドは、破棄されたプレーヤーのメッセージ ハンドラに DirectPlay8Event.DestroyPlayer メソッドを呼び出す。


DirectPlay8Peer.DestroyGroup

DirectPlay8Peer.CreateGroup メソッドにより作成されたグループを削除する。このメソッドは、グループ内の任意のピアから呼び出すことができる。

このメソッドは、グループ内のピアごとに DirectPlay8Event.AddRemovePlayerGroup メソッドを呼び出す。

DestroyGroup(idGroup As Long, lFlags As Long) As Long

指定項目

idGroup
削除するグループの識別子を指定する Long 値。
lFlags
このメソッドが処理される方法を制御するフラグ。このメソッドには、次のフラグを設定できる。
DPNOP_SYNC
メソッドを同期をとりながら処理する。

戻り値

この処理に対する非同期ハンドルを返す。これは、要求が非同期で処理される場合に、要求を取り消すために DirectPlay8Peer.CancelAsyncOperation メソッドの lAsyncHandle パラメータで使用されるハンドルである。

エラー コード

失敗した場合は、Err.Number に次のいずれかの値が設定される。

DPNERR_INVALIDFLAGS
DPNERR_INVALIDGROUP


DirectPlay8Peer.EnumHosts

Microsoft® DirectPlay® ゲームをホストするアプリケーションを列挙する。列挙基準を満たすアプリケーションが見つかると、アプリケーションのメッセージ ハンドラに DirectPlay8Event.EnumHostsResponse メソッドが呼び出される。このメソッドは、見つかったアプリケーションを記述する DPN_APPLICATION_DESC 型を格納する DPNMSG_ENUM_HOSTS_RESPONSE メッセージ型を含む。

EnumHosts(ApplicationDesc As DPN_APPLICATION_DESC, _
    AddrHost As DirectPlay8Address, _
    DeviceInfo As DirectPlay8Address, _
    lRetryCount As Long, _
    lRetryInterval As Long, _
    lTimeOut As Long, _
    lFlags As Long, _
    lFlags As CONST_DPNOPERATIONS, _
    UserData As Any, _
    UserDataSize As Long) As Long

指定項目

ApplicationDesc
列挙するアプリケーション ホストを指定する DPN_APPLICATION_DESC 構造体。列挙への応答数を減らすため、次のフィールドを指定できる。
guidApplication
検索するアプリケーションの GUID。指定されない場合は、すべてが検索される。
Password
指定するパスワード。セキュア セッションではパスワードがないと応答しない。
AddrHost
アプリケーションをホストしているコンピュータのアドレスを指定する DirectPlay8Address オブジェクト。
DeviceInfo
列挙するサービス プロバイダおよび設定を指定する DirectPlay8Address オブジェクト。
lRetryCount
列挙データを送信する回数を指定する値。このパラメータを 0 に設定すると、デフォルト値を指定できる。この値に INFINITE を設定した場合、列挙は取り消されるまで続行される。
lRetryInterval
列挙を試みる間隔 (ミリ秒単位) を指定する値。このパラメータを 0 に設定すると、デフォルト値を使用できる。
lTimeOut
列挙を実行する時間 (ミリ秒単位)。0 が指定された場合は、デフォルト値が使用される。INFINITE が指定された場合、列挙は取り消されるまで続行される。
lFlags
このメソッドが処理される方法を制御するフラグ。このメソッドには、次のフラグを設定できる。
DPNOP_SYNC
メソッドを同期をとりながら処理する。
UserData
列挙要求からホストに送信されるデータ ブロック。ネットワーク タイプによってデータのサイズに制限があるが、最低でも 512 バイトはサポートされている。
UserDataSize
UserData パラメータのデータのサイズ。

戻り値

この処理に対する非同期ハンドルを返す。これは、要求が非同期で処理される場合に、要求を取り消すために DirectPlay8Peer.CancelAsyncOperation メソッドの lAsyncHandle パラメータで使用されるハンドルである。

エラー コード

失敗した場合は、Err.Number に次のいずれかの値が設定される。

DPNERR_TIMEDOUT
DPNERR_INVALIDFLAGS
DPNERR_INVALIDPARAM

注意

列挙の処理にはさまざまな方法があるため、メディアに関して特に知識がない限り、アプリケーションでは lRetryInterval、lRetryCount、orlTimeOut を指定しないことを推奨する。


DirectPlay8Peer.GetApplicationDesc

接続されたアプリケーションに関するアプリケーションの記述全体を取得する。

GetApplicationDesc(lFlags As Long) _
    As DPN_APPLICATION_DESC

指定項目

lFlags
予約済み。0 に設定すること。

戻り値

アプリケーションを記述する DPN_APPLICATION_DESC 型を返す。

エラー コード

失敗した場合は、Err.Number に次のいずれかの値が設定される。

DPNERR_NOCONNECTION
DPNERR_INVALIDFLAGS
DPNERR_BUFFERTOOSMALL
DPNERR_INVALIDPARAM


DirectPlay8Peer.GetCaps

現在のオブジェクトに対する DPN_CAPS 型を取得する。

GetCaps() As DPN_CAPS

戻り値

指定したサービス プロバイダに関する情報を受け取る DPN_SP_CAPS 型を返す。

エラー コード

失敗した場合は、Err.Number に次のいずれかの値が設定される。

DPNERR_INVALIDOBJECT
DPNERR_INVALIDPOINTER
DPNERR_INVALIDPARAM
DPNERR_UNINITIALIZED

注意

DirectPlay8Peer.RegisterMessageHandler の呼び出しが成功した後に、このメソッドを呼び出す必要がある。


DirectPlay8Peer.GetPlayerOrGroup

指定されたクライアントまたはグループの識別子を取得する。アプリケーションのクライアントまたはグループの数は、DirectPlay8Peer.GetCountClientsAndGroups を呼び出して確認できる。

GetPlayerOrGroup(lIndex As Long) As Long

指定項目

lIndex
クライアントまたはグループのインデックス。

戻り値

クライアントまたはグループの識別情報を返す。

エラー コード

失敗した場合は、Err.Number に次のいずれかの値が設定される。

DPNERR_INVALIDOBJECT
DPNERR_INVALIDPARAM


DirectPlay8Peer.GetConnectionInfo

ローカル エンドポイントとホスト間の接続に関する統計情報を取得する。

GetConnectionInfo() As DPN_CONNECTION_INFO

戻り値

指定した接続に関する情報を取得する DPN_CONNECTION_INFO 型を返す。

エラー コード

失敗した場合は、Err.Number に次のいずれかの値が設定される。

DPNERR_INVALIDOBJECT
DPNERR_INVALIDPOINTER
DPNERR_INVALIDPARAM
DPNERR_UNINITIALIZED

注意

Connect の呼び出しが成功した後にのみ、このメソッドを呼び出すことができる。


DirectPlay8Peer.GetCountClientsAndGroups

セッションのピアまたはグループの数を取得する。

GetCountClientsAndGroups( _
    lFlags As CONST_DPNENUMCLIENTGROUPFLAGS) As Long

指定項目

lFlags
列挙動作を記述するフラグ。CONST_DPNENUMCLIENTGROUPFLAGS 列挙の次のいずれかのフラグを設定できる。

エラー コード

失敗した場合は、Err.Number に次のいずれかの値が設定される。

DPNERR_INVALIDFLAGS


DirectPlay8Peer.GetCountGroupMembers

グループ内のプレーヤーの数を取得する。

GetCountGroupMembers(dpid As Long) As Long

指定項目

dpid
グループの識別情報を指定する Long 値。

戻り値

グループ内のプレーヤーの数を返す。

エラー コード

失敗した場合は、Err.Number に次のいずれかの値が設定される。

DPNERR_INVALIDGROUP
DPNERR_INVALIDFLAGS

注意

プレーヤーの情報は頻繁に変化するため、返される必要なバッファ サイズは以降の呼び出しで変わる場合がある。メソッドが成功するまで、バッファを確認し、再割り当てする。


DirectPlay8Peer.GetCountServiceProviders

アプリケーションで利用できる登録済みサービス プロバイダの数を取得する。

GetCountServiceProviders() As Long

戻り値

アプリケーションで利用できる登録済みサービス プロバイダの数を返す。

エラー コード

失敗した場合は、Err.Number に次のいずれかの値が設定される。

DPNERR_INVALIDOBJECT


DirectPlay8Peer.GetEnumHostResponseAddress

ホストのアドレスを取得する。

GetEnumHostResponseAddress( _
    AppDesc As DPN_APPLICATION_DESC) _
    As DirectPlay8Address

指定項目

AppDesc
アプリケーションを記述する DPN_APPLICATION_DESC 型。

戻り値

ホストのアドレスを指定する DirectPlay8Address オブジェクトを返す。

エラー コード

失敗した場合は、Err.Number に次のいずれかの値が設定される。

DPNERR_INVALIDPARAM


DirectPlay8Peer.GetGroupInfo

グループ名など、グループに関連するデータのブロックを取得する。

このメソッドは、通常、DirectPlay がグループ データが変更されたことを示す DirectPlay8Event.InfoNotify メソッドを呼び出した後に呼び出される。

GetGroupInfo(idGroup As Long) As DPN_GROUP_INFO

指定項目

idGroup
データ ブロックを取得するグループの識別子を指定する Long 値。

戻り値

グループ データを記述する DPN_GROUP_INFO 型を返す。

エラー コード

失敗した場合は、Err.Number に次のいずれかの値が設定される。

DPNERR_INVALIDGROUP
DPNERR_INVALIDFLAGS


DirectPlay8Peer.GetGroupMember

グループの指定したメンバの識別子を取得する。グループのプレーヤー数は、DirectPlay8Peer.GetCountGroupMembers を呼び出して確認できる。

GetGroupMember(lIndex As Long, dpid As Long) As Long

指定項目

lIndex
グループ内のプレーヤーのインデックス値。
dpid
グループの識別情報を指定する Long 値。

戻り値

プレーヤーの識別情報を指定する Long 値を返す。

エラー コード

失敗した場合は、Err.Number に次のいずれかの値が設定される。

DPNERR_INVALIDGROUP
DPNERR_INVALIDPARAM


DirectPlay8Peer.GetPeerAddress

セッション内の指定されたプレーヤーのアドレスを取得する。

GetPeerAddress(idPlayer As Long) As DirectPlay8Address

指定項目

idPlayer
プレーヤーの識別情報を指定する Long 値。

戻り値

プレーヤーのアドレスを指定する DirectPlay8Address オブジェクトを返す。

エラー コード

失敗した場合は、Err.Number に次のいずれかの値が設定される。

DPNERR_INVALIDOBJECT
DPNERR_UNINITIALIZED


DirectPlay8Peer.GetPeerInfo

指定されたピアに対して設定されたプレーヤー情報を取得する。

GetPeerInfo(idPeer As Long) As DPN_PLAYER_INFO

指定項目

idPeer
情報の取得対象となるピアの識別子を指定する長整数型 (Long) の値。

戻り値

プレーヤーの情報を記述する DPN_PLAYER_INFO 型を返す。

エラー コード

失敗した場合は、Err.Number に次のいずれかの値が設定される。

DPNERR_INVALIDPLAYER
DPNERR_INVALIDPARAM

注意

このメソッドは、DirectPlay がグループ データが変更されたことを示す DirectPlay8Event.InfoNotify メソッドを呼び出した後に呼び出される。


DirectPlay8Peer.GetSendQueueInfo

アプリケーションで送信キューのサイズを監視するために使用する。Microsoft® DirectPlay® では、受け取り側のコンピュータの処理速度よりも高速にメッセージを送信することはない。そのため、送信元のコンピュータが、送信先が受け取れる速さよりも高速にメッセージを送信した場合、メッセージは送信側のキューに蓄積される。アプリケーションにより、送信キューのサイズが大きすぎると登録された場合は、メッセージの送信レートを低下させる必要がある。

GetSendQueueInfo(lNumMsgs As Long, lNumBytes As Long)

指定項目

lNumMsgs
現在キューに蓄積されているメッセージの数。
lNumBytes
現在キューに蓄積されているメッセージ データの総バイト数。

エラー コード

失敗した場合は、Err.Number に次のいずれかの値が設定される。

DPNERR_INVALIDPARAM


DirectPlay8Peer.GetServiceProvider

指定されたサービス プロバイダに関する情報を取得する。このメソッドを呼び出す前に、DirectPlay8Peer.GetCountServiceProviders メソッドを呼び出して、アプリケーションで利用可能な登録済みサービス プロバイダの数を取得する。

GetServiceProvider(lIndex As Long) As DPN_SERVICE_PROVIDER_INFO

指定項目

lIndex
特定のサービス プロバイダを指定するインデックス値。

戻り値

サービス プロバイダを記述する DPN_SERVICE_PROVIDER_INFO 型を返す。

エラー コード

失敗した場合は、Err.Number に次のいずれかの値が設定される。

DPNERR_INVALIDPARAM


DirectPlay8Peer.GetSPCaps

指定されたサービス プロバイダの DPN_SP_CAPS 構造体を取得する。

GetSPCaps(guidSP As String) As DPN_SP_CAPS

指定項目

guidSP
情報を取得するサービス プロバイダの GUID を指定する文字列。

戻り値

指定されたサービス プロバイダに関する情報を受け取る DPN_SP_CAPS 型を返す。

エラー コード

失敗した場合は、Err.Number に次のいずれかの値が設定される。

DPNERR_INVALIDOBJECT
DPNERR_INVALIDPOINTER
DPNERR_INVALIDPARAM
DPNERR_UNINITIALIZED

注意

DirectPlay8Peer.RegisterMessageHandler の呼び出しが成功した後に、このメソッドを呼び出す必要がある。


DirectPlay8Peer.Host

ピアツーピア セッションのホストを指定する。

Host(AppDesc As DPN_APPLICATION_DESC, _
    Address As DirectPlay8Address)

指定項目

AppDesc
アプリケーションを記述する DPN_APPLICATION_DESC 型。
Address
サービス プロバイダのデバイスのアドレスまたはアプリケーションをホストするサービス プロバイダを指定する DirectPlay8Address オブジェクト。

エラー コード

失敗した場合は、Err.Number に次のいずれかの値が設定される。

DPNERR_INVALIDPARAM


DirectPlay8Peer.RegisterLobby

ロビーへのアプリケーションの登録または登録の解除を行う。

RegisterLobby(dpnHandle As Long, _
    LobbyApp As DirectPlay8LobbiedApplication, _
    lFlags As Long)

指定項目

dpnHandle
DirectPlay8LobbiedApplication.UpdateStatus への呼び出しを行うときに使用する接続ハンドル。
LobbyApp
アプリケーションを指定する DirectPlay8LobbiedApplication オブジェクト。
lFlags
アプリケーションの登録または登録解除を指定するには、2 つある CONST_DPNLOBBY 列挙値のうちの 1 つをこのパラメータに設定する。

エラー コード

失敗した場合は、Err.Number に次のいずれかの値が設定される。

DPNERR_INVALIDPARAM

注意

アプリケーションがロビーに登録されると、ロビー クライアントはゲーム ステータス内の変更通知を自動的に受け取る。


DirectPlay8Peer.RegisterMessageHandler

DirectPlay8Peer クラスからメッセージを受信する、クライアントのコード内のエントリ ポイントを登録する。このクラスのほかのメソッドを呼び出す前に、このメソッドを呼び出す必要がある。

RegisterMessageHandler(event As DirectPlay8Event)

指定項目

event
クライアントおよびサーバーによって生成されたメッセージを受け取る DirectPlay8Event オブジェクト。

エラー コード

失敗した場合は、Err.Number に次のいずれかの値が設定される。

DPNERR_ALREADYREGISTERED

注意

新しいメッセージ ハンドラを登録する場合、まず DirectPlay8Peer.UnRegisterMessageHandler を呼び出して、現在のメッセージ ハンドラの登録を解除する必要がある。


DirectPlay8Peer.RemovePlayerFromGroup

グループからピアを削除する。

このメソッドが呼び出されると、DirectPlay は各プレーヤーの DirectPlay8Event.AddRemovePlayerGroup メソッドを呼び出して、プレーヤーにグループからメンバが削除されたことを通知する。

RemovePlayerFromGroup(idGroup As Long, _
    idClient As Long, _
    lFlags As Long) As Long

指定項目

idGroup
ピアが削除されるグループの識別子を指定する長整数型 (Long) の値。
idClient
グループから削除されるピアの識別子を指定する長整数型 (Long) の値。
lFlags
このメソッドが処理される方法を制御するフラグ。このメソッドには、次のフラグを設定できる。
DPNOP_SYNC
メソッドを同期をとりながら処理する。

戻り値

この処理に対する非同期ハンドルを返す。これは、要求が非同期で処理される場合に、要求を取り消すために DirectPlay8Peer.CancelAsyncOperation メソッドの lAsyncHandle パラメータで使用されるハンドルである。

エラー コード

失敗した場合は、Err.Number に次のいずれかの値が設定される。

DPNERR_INVALIDGROUP
DPNERR_INVALIDFLAGS
DPNERR_INVALIDPLAYER


DirectPlay8Peer.SendTo

指定されたプレーヤーにデータを送信する。メッセージは同期または非同期で送信することができる。

SendTo(idSend As Long, _
    buffer() As BYTE, _
    lPriority As Long, _
    lTimeOut As Long, _
    lFlags As CONST_DPNSENDFLAGS) As Long

指定項目

idSend
データを受け取るプレーヤーの識別子を指定する Long 値。セッション内のすべてのプレーヤーにメッセージを送るには、CONST_DPNPLAYERGROUPFLAGS 列挙の DPNID_ALL_PLAYERS_GROUP 値をこのパラメータに設定する。
buffer()
送信するデータを記述する BYTE 型の配列。
lPriority
メッセージの優先順位。
lTimeOut
メッセージの送信を待つ時間 (ミリ秒単位)。メッセージが lTimeOut 値で送信されていない場合、メッセージは送信されない。メッセージの送信に対してタイム アウトが必要でない場合は、このパラメータを 0 に設定する。
lFlags
送信動作を記述するフラグ。CONST_DPNSENDFLAGS 列挙で定義された次の 1 つ以上のフラグを設定できる。

戻り値

この処理に対する非同期ハンドルを返す。これは、要求が非同期で処理される場合に、要求を取り消すために DirectPlay8Peer.CancelAsyncOperation メソッドの lAsyncHandle パラメータで使用されるハンドルである。

エラー コード

失敗した場合は、Err.Number に次のいずれかの値が設定される。

DPNERR_INVALIDFLAGS
DPNERR_TIMEDOUT

注意

このメソッドは、受信者のメッセージ ハンドラに DirectPlay8Event.Receive メソッドを呼び出す。SendTo 要求が完了すると、送信側のメッセージ ハンドラに DirectPlay8Event.SendComplete メソッドが呼び出される。SendComplete メソッドは、DPNMSG_SEND_COMPLETE メッセージ型を保持する。要求が成功したか失敗したかは、このメッセージ型の hResultCode メンバに保持される。アプリケーションは IDirectPlay8Client、IDirectPlay8Server、または IDirectPlay8Peer で Close を呼び出す前や最終リリースをする前に、CancelAsyncOperation を呼び出して残っている Send をキャンセルすべきである。それに失敗すると予期せぬ結果が起きる。


DirectPlay8Peer.SetApplicationDesc

ホストされるアプリケーションの設定を変更する。変更できるのは、いくつかの設定のみである。

SetApplicationDesc(AppDesc As DPN_APPLICATION_DESC, _
    lFlags As Long)

指定項目

AppDesc
変更するアプリケーションの設定を記述する DPN_APPLICATION_DESC 型。
lFlags
予約済み。0 に設定すること。

エラー コード

失敗した場合は、Err.Number に次のいずれかの値が設定される。

DPNERR_INVALIDFLAGS

注意

このメソッドを使って、DPN_APPLICATION_DESC 型の以下のメンバのみを変更できる。

  • lMaxPlayers
  • SessionName
  • Password


DirectPlay8Peer.SetCaps

セッションの能力を設定する。

SetCaps(caps As DPN_CAPS, lFlags As Long)

指定項目

caps
現在のセッションに関する設定に使用される DPN_CAPS 型。
lFlags
予約済み。0 に設定すること。

エラー コード

失敗した場合は、Err.Number に次のいずれかの値が設定される。

DPNERR_INVALIDOBJECT
DPNERR_INVALIDPOINTER
DPNERR_INVALIDPARAM
DPNERR_UNINITIALIZED

注意

DirectPlay8Peer.RegisterMessageHandler の呼び出しが成功した後に、このメソッドを呼び出す必要がある。


DirectPlay8Peer.SetGroupInfo

グループ名など、グループに関連するデータのブロックを設定する。

DirectPlay は各プレーヤーの DirectPlay8Event.InfoNotify メソッドを呼び出して、プレーヤーにグループの情報が変更されたことを通知する。

SetGroupInfo(idGroup As Long, _
    PlayerInfo As DPN_GROUP_INFO, _
    lFlags As Long) As Long

指定項目

idGroup
データ ブロックを変更するグループの識別子を指定する Long 型。
PlayerInfo
設定するグループ データを記述する DPN_GROUP_INFO 型。
lFlags
このメソッドが処理される方法を制御するフラグ。このメソッドには次のフラグを設定できる。
DPNOP_SYNC
メソッドを同期をとりながら処理する。

戻り値

この処理に対する非同期ハンドルを返す。これは、要求が非同期で処理される場合に、要求を取り消すために DirectPlay8Peer.CancelAsyncOperation メソッドの lAsyncHandle パラメータで使用されるハンドルである。

エラー コード

失敗した場合は、Err.Number に次のいずれかの値が設定される。

DPNERR_INVALIDGROUP
DPNERR_INVALIDFLAGS


DirectPlay8Peer.SetPeerInfo

アプリケーションとのピアの静的設定を設定する。アプリケーションに基本的なプレーヤー情報を転送するには、接続前にこのメソッドを呼び出す。ピアが正しくアプリケーションに接続すると、ほかのプレーヤーはこのメソッドで取得された情報を DirectPlay8Peer.GetPeerInfo メソッドを呼び出して取得できる。

SetPeerInfo(PlayerInfo As DPN_PLAYER_INFO) As Long

指定項目

PlayerInfo
設定するピア情報を保持する DPN_PLAYER_INFO 型。

戻り値

この処理に対する非同期ハンドルを返す。これは、要求が非同期で処理される場合に、要求を取り消すために DirectPlay8Peer.CancelAsyncOperation メソッドの lAsyncHandle パラメータで使用されるハンドルである。

エラー コード

失敗した場合は、Err.Number に次のいずれかの値が設定される。

DPNERR_NOCONNECTION
DPNERR_INVALIDFLAGS
DPNERR_INVALIDPARAM

注意

DirectPlay8Peer.SetPeerInfo メソッドを使用すると処理に負担がかかるため、非静的情報は DirectPlay8Peer.SendTo メソッドを使用して転送すること。

アプリケーションへの接続後、このメソッドを使用してピア情報を変更できる。接続後このメソッドが呼び出されると、DirectPlay は各プレーヤーの DirectPlay8Event.InfoNotify メソッドを呼び出して、プレーヤーにデータが更新されたことを通知する。


DirectPlay8Peer.SetSPCaps

指定されたサービス プロバイダの能力を設定する。

SetSPCaps(guidSP As String, spCaps As DPN_SP_CAPS)

指定項目

guidSP
情報を設定するサービス プロバイダの GUID を指定する文字列。
spCaps
指定したサービス プロバイダに関する情報を設定する DPN_SP_CAPS 型。

エラー コード

失敗した場合は、Err.Number に次のいずれかの値が設定される。

DPNERR_INVALIDOBJECT
DPNERR_INVALIDPOINTER
DPNERR_INVALIDPARAM
DPNERR_UNINITIALIZED

注意

DirectPlay8Peer.RegisterMessageHandler の呼び出しが成功した後に、このメソッドを呼び出す必要がある。


DirectPlay8Peer.TerminateSession

現在の Microsoft® DirectPlay® セッションを終了する。

TerminateSession(lFlags As Long, _
    UserData As Any, _
    UserDataSize As Long)

指定項目

lFlags
予約済み。0 に設定すること。
UserData
終了データへのポインタ。
UserDataSize
UserData パラメータに保持されるデータのサイズ。

注意

このメソッドはホスト プレーヤーのみ呼び出すことができる。

このメソッドが呼び出されると、セッションに接続されているすべてのプレーヤーのメッセージ ハンドラで DirectPlay8Event.TerminateSession メソッドが呼び出される。


DirectPlay8Peer.UnregisterMessageHandler

現在のメッセージ ハンドラの登録を解除する。

UnRegisterMessageHandler()

注意

新しいメッセージ ハンドラを登録するには、その前にこのメソッドを呼び出す必要がある。


DirectPlay8Server

アプリケーションは、DirectPlay8Server クラスのメソッドを使用して、Microsoft® DirectPlay® のクライアント/サーバー トランスポート セッションに対するサーバーの作成と管理を行う。

DirectPlay8Server クラスのメソッドは、以下のグループにまとめることができる。

セッション管理 | Close
 | GetApplicationDesc
 | GetCaps
 | GetConnectionInfo
 | GetCountServiceProviders
 | GetServiceProvider
 | GetSPCaps
 | Host
 | SetApplicationDesc
 | SetCaps
 | SetSPCaps
メッセージ管理 | GetSendQueueInfo
 | RegisterMessageHandler
 | SendTo
 | UnregisterMessageHandler
プレーヤー管理 | DestroyClient
 | GetClientAddress
 | GetClientInfo
 | GetClientOrGroup
 | GetCountClientsAndGroups
 | RemoveClientFromGroup
 | SetServerInfo
グループ管理 | AddClientToGroup
 | CreateGroup
 | DestroyGroup
 | GetCountGroupMembers
 | GetGroupInfo
 | GetGroupMember
 | SetGroupInfo
その他 | CancelAsyncOperation
 | RegisterLobby


DirectPlay8Server.AddClientToGroup

グループにクライアントを追加する。

AddClientToGroup(idGroup As Long, _
    idClient As Long,
    lFlags As Long) As Long

指定項目

idGroup
クライアントを追加する先のグループの識別子を指定する長整数型 (Long) の値。
idClient
グループに追加されるクライアントの識別子を指定する長整数型 (Long) の値。
lFlags
このメソッドが処理される方法を制御するフラグ。このメソッドには、次のフラグを設定できる。
DPNOP_SYNC
メソッドを同期をとりながら処理する。

戻り値

この処理に対する非同期ハンドルを返す。これは、要求が非同期で処理される場合に、要求を取り消すために DirectPlay8Server.CancelAsyncOperation メソッドの lAsyncHandle パラメータで使用されるハンドルである。

エラー コード

失敗した場合は、Err.Number に次のいずれかの値が設定される。

DPNERR_INVALIDGROUP
DPNERR_INVALIDFLAGS

注意

クライアントはそれ自体またはほかのクライアントを既存のグループに追加できる。クライアントがグループに正しく追加されると、グループに送信されるすべてのメッセージがそのクライアントにも送信される。

クライアントがそれ自体をグループに追加する場合は、idClient パラメータに DPNID_ME を渡す。


DirectPlay8Server.CancelAsyncOperation

非同期要求を取り消す。デフォルトでは、DirectPlay8Server クラスの多くのメソッドが非同期に実行される。状況に応じて、要求が処理される前にその要求を取り消したい場合もある。非同期で実行できるこのクラスのメソッドはすべて lAsyncHandle パラメータを返す。

このメソッドの lAsyncHandle パラメータに要求の lAsyncHandle を渡すことによって、特定の要求が取り消される。このメソッドを呼び出し、hAsyncHandle パラメータに 0 を、lFlags パラメータに DPNCANCEL_ALL_OPERATIONS を指定することによって、待機中のすべての非同期処理を取り消すことができる。特定のハンドルがこのメソッドに指定された場合は、lFlags パラメータに 0 を渡す必要がある。

CancelAsyncOperation(lAsyncHandle As Long, _
    lFlags As CONST_DPNCANCELFLAGS)

指定項目

lAsyncHandle
停止する非同期処理のハンドル。この値を 0 に設定して、すべての要求または特定の種類の非同期要求を停止することができる。取り消す要求の特定のハンドルが指定された場合、lFlags パラメータは 0 にする必要がある。
lFlags
取り消す非同期要求を指定するフラグ。このフラグに CONST_DPNCANCELFLAGS 列挙のいずれかのフラグを設定できる。

エラー コード

失敗した場合は、Err.Number に次のいずれかの値が設定される。

DPNERR_PENDING
DPNERR_INVALIDFLAGS
DPNERR_CANNOTCANCEL
DPNERR_INVALIDHANDLE

注意

DirectPlay8Server.SendTo メソッドから返されたハンドルを指定すると、送信を取り消すことができる。DirectPlay8Event.SendComplete メソッドは、メッセージが DPNSEND_NOCOMPLETE フラグを設定して送信された場合を除き、その後も呼び出される。DirectPlay8Peer.CancelAsyncOperation を呼び出して送信処理を取り消した場合、DirectPlay8Event.SendComplete メソッドに渡された DPNMSG_SEND_COMPLETE 型の hResultCode メンバに、DPNERR_CANCELLED が設定される。


DirectPlay8Server.Close

セッションにより開いた接続を閉じる。

Close();

エラー コード

失敗した場合は、Err.Number に次のいずれかの値が設定される。

DPNERR_UNINITIALIZED


DirectPlay8Server.CreateGroup

現在のセッション内でグループを作成する。グループはプレーヤーの論理的な集まりである。

CreateGroup(GroupInfo As DPN_GROUP_INFO, _
    lFlags As Long) As Long

指定項目

GroupInfo
グループの記述を保持する DPN_GROUP_INFO 構造体。
lFlags
このメソッドが処理される方法を制御するフラグ。このメソッドには、次のフラグを設定できる。
DPNOP_SYNC
メソッドを同期をとりながら処理する。

戻り値

この処理に対する非同期ハンドルを返す。これは、要求が非同期で処理される場合に、要求を取り消すために DirectPlay8Server.CancelAsyncOperation メソッドの lAsyncHandle パラメータで使用されるハンドルである。

エラー コード

失敗した場合は、Err.Number に次のいずれかの値が設定される。

DPNERR_INVALIDFLAGS

注意

Microsoft® DirectPlay® は、階層グループを保持しない。これは、これらのグループがフラット グループとグループ データの活用により簡単に実装できるためである。


DirectPlay8Server.DestroyClient

セッションからクライアントを削除する。

DestroyClient(idClient As Long, _
    lFlags As Long, _
    UserData As Any, _
    UserDataSize As Long)

指定項目

idClient
削除するクライアントの識別子を指定する長整数型 (Long) の値。
lFlags
予約済み。0 に設定すること。
UserData
アプリケーション固有のユーザー データ。
UserDataSize
UserData パラメータに保持されるデータ サイズを指定する Long 値。

エラー コード

失敗した場合は、Err.Number に次のいずれかの値が設定される。

DPNERR_NOTHOST
DPNERR_INVALIDPLAYER
DPNERR_INVALIDPARAM

注意

このメソッドは、破棄されたプレーヤーのメッセージ ハンドラに DirectPlay8Event.DestroyPlayer メソッドを呼び出す。


DirectPlay8Server.DestroyGroup

DirectPlay8Server.CreateGroup メソッドにより作成されたグループを削除する。

DestroyGroup(idGroup As Long, lFlags As Long) As Long

指定項目

idGroup
削除するグループの識別子を指定する長整数型 (Long) の値。
lFlags
このメソッドが処理される方法を制御するフラグ。このメソッドには、次のフラグを設定できる。
DPNOP_SYNC
メソッドを同期をとりながら処理する。

戻り値

この処理に対する非同期ハンドルを返す。これは、要求が非同期で処理される場合に、要求を取り消すために DirectPlay8Server.CancelAsyncOperation メソッドの lAsyncHandle パラメータで使用されるハンドルである。

エラー コード

失敗した場合は、Err.Number に次のいずれかの値が設定される。

DPNERR_INVALIDFLAGS
DPNERR_INVALIDGROUP


DirectPlay8Server.GetApplicationDesc

接続されたアプリケーションに関するアプリケーションの記述全体を取得する。

GetApplicationDesc(lFlags As Long) _
    As DPN_APPLICATION_DESC

指定項目

lFlags
予約済み。0 に設定すること。

戻り値

アプリケーションを記述する DPN_APPLICATION_DESC 型を返す。

エラー コード

失敗した場合は、Err.Number に次のいずれかの値が設定される。

DPNERR_NOCONNECTION
DPNERR_INVALIDFLAGS
DPNERR_BUFFERTOOSMALL
DPNERR_INVALIDPARAM


DirectPlay8Server.GetCaps

現在のオブジェクトに対する DPN_CAPS 型を取得する。

GetCaps() As DPN_CAPS

戻り値

Caps 情報が格納される DPN_CAPS 型を返す。

エラー コード

失敗した場合は、Err.Number に次のいずれかの値が設定される。

DPNERR_INVALIDOBJECT
DPNERR_INVALIDPOINTER
DPNERR_INVALIDPARAM
DPNERR_UNINITIALIZED

注意

DirectPlay8Server.RegisterMessageHandler の呼び出しが成功した後に、このメソッドを呼び出す必要がある。


DirectPlay8Server.GetClientAddress

セッション内の指定されたプレーヤーのアドレスを取得する。

GetClientAddress(idPlayer As Long) As DirectPlay8Address

指定項目

idPlayer
プレーヤーの識別情報を指定する Long 値。

戻り値

プレーヤーのアドレスを指定する DirectPlay8Address オブジェクトを返す。

エラー コード

失敗した場合は、Err.Number に次のいずれかの値が設定される。

DPNERR_INVALIDOBJECT
DPNERR_UNINITIALIZED


DirectPlay8Server.GetClientInfo

指定されたクライアントに対して設定されたプレーヤー情報を取得する。

GetClientInfo(idClient As Long) As DPN_PLAYER_INFO

指定項目

idClient
情報を取得するクライアントの識別子を指定する長整数型 (Long) の値。

戻り値

プレーヤーの情報を記述する DPN_PLAYER_INFO 型を返す。

エラー コード

失敗した場合は、Err.Number に次のいずれかの値が設定される。

DPNERR_INVALIDPLAYER
DPNERR_INVALIDPARAM

注意

このメソッドは、DirectPlay がプレーヤー データが変更されたことを示す DirectPlay8Event.InfoNotify メソッドを呼び出した後に呼び出される。


DirectPlay8Server.GetClientOrGroup

指定されたクライアントまたはグループの識別子を取得する。アプリケーションのクライアントまたはグループの数は、DirectPlay8Server.GetCountClientsAndGroups を呼び出して確認できる。

GetClientOrGroup(lIndex As Long) As Long

指定項目

lIndex
クライアントまたはグループのインデックス。

戻り値

クライアントまたはグループの識別情報を返す。

エラー コード

失敗した場合は、Err.Number に次のいずれかの値が設定される。

DPNERR_INVALIDOBJECT
DPNERR_INVALIDPARAM


DirectPlay8Server.GetConnectionInfo

指定されたプレーヤーとサーバー間の接続に関する統計情報を取得する。

GetConnectionInfo(idPlayer As Long) As DPN_CONNECTION_INFO

Parameter

idPlayer
プレーヤーの識別子を指定する Long 値。

戻り値

指定された接続に関する情報を取得する DPN_CONNECTION_INFO 型を返す。

エラー コード

失敗した場合は、Err.Number に次のいずれかの値が設定される。

DPNERR_INVALIDOBJECT
DPNERR_INVALIDPOINTER
DPNERR_INVALIDPARAM
DPNERR_UNINITIALIZED

注意

Connect の呼び出しが成功した後にのみ、このメソッドを呼び出すことができる。


DirectPlay8Server.GetCountClientsAndGroups

セッションのクライアントまたはグループの数を取得する。

GetCountClientsAndGroups( _
    lFlags As CONST_DPNENUMCLIENTGROUPFLAGS) As Long

指定項目

lFlags
列挙動作を記述するフラグ。CONST_DPNENUMCLIENTGROUPFLAGS 列挙からのいずれかのフラグを設定できる。

エラー コード

失敗した場合は、Err.Number に次のいずれかの値が設定される。

DPNERR_INVALIDFLAGS


DirectPlay8Server.GetCountGroupMembers

グループ内のプレーヤーの数を取得する。

GetCountGroupMembers(dpid As Long) As Long

指定項目

dpid
グループの識別情報を指定する Long 値。

戻り値

グループ内のプレーヤーの数を返す。

エラー コード

失敗した場合は、Err.Number に次のいずれかの値が設定される。

DPNERR_INVALIDGROUP
DPNERR_INVALIDFLAGS

注意

プレーヤーの情報は頻繁に変化するため、返される必要なバッファ サイズは以降の呼び出しで変わる場合がある。メソッドが成功するまで、バッファを確認し、再割り当てする。


DirectPlay8Server.GetCountServiceProviders

アプリケーションで利用できる登録済みサービス プロバイダの数を取得する。

GetCountServiceProviders() As Long

戻り値

アプリケーションで利用できる登録済みサービス プロバイダの数を返す。

エラー コード

失敗した場合は、Err.Number に次のいずれかの値が設定される。

DPNERR_INVALIDOBJECT


DirectPlay8Server.GetGroupInfo

グループ名など、グループに関連するデータのブロックを取得する。

このメソッドは、DirectPlay がグループ データが変更されたことを示す DirectPlay8Event.InfoNotify メソッドを呼び出した後に呼び出される。

GetGroupInfo(idGroup As Long) As DPN_GROUP_INFO

指定項目

idGroup
データ ブロックを取得するグループの識別子を指定する Long 値。

戻り値

グループ データを記述する DPN_GROUP_INFO 型を返す。

エラー コード

失敗した場合は、Err.Number に次のいずれかの値が設定される。

DPNERR_INVALIDGROUP
DPNERR_INVALIDFLAGS


DirectPlay8Server.GetGroupMember

グループの指されたメンバの識別子を取得する。グループのプレーヤー数は、DirectPlay8Server.GetCountGroupMembers を呼び出して確認できる。

GetGroupMember(lIndex As Long, dpid As Long) As Long

指定項目

lIndex
グループ内のプレーヤーのインデックス値。
dpid
グループの識別情報を指定する Long 値。

戻り値

プレーヤーの識別情報を指定する Long 値。

エラー コード

失敗した場合は、Err.Number に次のいずれかの値が設定される。

DPNERR_INVALIDGROUP
DPNERR_INVALIDPARAM


DirectPlay8Server.GetSendQueueInfo

アプリケーションで送信キューのサイズを監視するために使用する。Microsoft® DirectPlay® では、受け取り側のコンピュータの処理速度よりも高速にメッセージを送信することはない。そのため、送信元のコンピュータが、送信先が受け取れる速さよりも高速にメッセージを送信した場合、メッセージは送信側のキューに蓄積される。アプリケーションにより、送信キューのサイズが大きすぎると登録された場合は、メッセージの送信レートを低下させる必要がある。

GetSendQueueInfo(idPlayer As Long, _
    lNumMsgs As Long, _
    lNumBytes As Long)

指定項目

idPlayer
プレーヤーの識別子を指定する Long 値。
lNumMsgs
現在キューに蓄積されているメッセージの数。
lNumBytes
現在キューに蓄積されているメッセージ データの総バイト数。

エラー コード

失敗した場合は、Err.Number に次のいずれかの値が設定される。

DPNERR_INVALIDPARAM


DirectPlay8Server.GetServiceProvider

指定されたサービス プロバイダに関する情報を取得する。このメソッドを呼び出す前に、DirectPlay8Server.GetCountServiceProviders メソッドを呼び出して、アプリケーションで利用可能な登録済みサービス プロバイダの数を取得する。

GetServiceProvider(lIndex As Long) As DPN_SERVICE_PROVIDER_INFO

指定項目

lIndex
特定のサービス プロバイダを指定するインデックス値。

戻り値

サービス プロバイダを記述する DPN_SERVICE_PROVIDER_INFO 型を返す。

エラー コード

失敗した場合は、Err.Number に次のいずれかの値が設定される。

DPNERR_INVALIDPARAM


DirectPlay8Server.GetSPCaps

指定されたサービス プロバイダの DPN_SP_CAPS 構造体を取得する。

GetSPCaps(guidSP As String) As DPN_SP_CAPS

指定項目

guidSP
情報を取得するサービス プロバイダの GUID を指定する文字列。

戻り値

指定したサービス プロバイダに関する情報を受け取る DPN_SP_CAPS 型を返す。

エラー コード

失敗した場合は、Err.Number に次のいずれかの値が設定される。

DPNERR_INVALIDOBJECT
DPNERR_INVALIDPOINTER
DPNERR_INVALIDPARAM
DPNERR_UNINITIALIZED

注意

DirectPlay8Server.RegisterMessageHandler の呼び出しが成功した後に、このメソッドを呼び出す必要がある。


DirectPlay8Server.Host

クライアント/サーバー セッションのホストを指定する。

Host(AppDesc As DPN_APPLICATION_DESC, _
    Address As DirectPlay8Address)

指定項目

AppDesc
アプリケーションを記述する DPN_APPLICATION_DESC 型。
Address
サービス プロバイダのデバイスのアドレスまたはアプリケーションをホストするサービス プロバイダを指定する DirectPlay8Address オブジェクト。

エラー コード

失敗した場合は、Err.Number に次のいずれかの値が設定される。

DPNERR_INVALIDPARAM


DirectPlay8Server.RegisterLobby

起動したアプリケーションがゲームの状態を自動的にロビーに伝達できるようにする。

RegisterLobby(LobbyApp As DirectPlay8LobbiedApplication)

指定項目

LobbyApp
アプリケーションを指定する DirectPlay8LobbiedApplication オブジェクト。

エラー コード

失敗した場合は、Err.Number に次のいずれかの値が設定される。

DPNERR_INVALIDPARAM


DirectPlay8Server.RegisterMessageHandler

DirectPlay8Server クラスおよび接続済みクライアントからメッセージを受信する、サーバーのコード内のエントリ ポイントを登録する。

RegisterMessageHandler(event As DirectPlay8Event)

指定項目

event
クライアントおよびサーバーによって生成されたメッセージを受け取る DirectPlay8Event オブジェクト。

エラー コード

失敗した場合は、Err.Number に次のいずれかの値が設定される。

DPNERR_ALREADYREGISTERED

注意

新しいメッセージ ハンドラを登録する場合、まず DirectPlay8Server.UnRegisterMessageHandler を呼び出して、現在のメッセージ ハンドラの登録を解除する必要がある。


DirectPlay8Server.RemoveClientFromGroup

グループからクライアントを削除する。

RemoveClientFromGroup(idGroup As Long, _
    idClient As Long, _
    lFlags As Long) As Long

指定項目

idGroup
クライアントが削除されるグループの識別子を指定する長整数型 (Long) の値。
idClient
グループから削除されるクライアントの識別子を指定する長整数型 (Long) の値。
lFlags
このメソッドが処理される方法を制御するフラグ。このメソッドには、次のフラグを設定できる。
DPNOP_SYNC
メソッドを同期をとりながら処理する。

戻り値

この処理に対する非同期ハンドルを返す。これは、要求が非同期で処理される場合に、要求を取り消すために DirectPlay8Server.CancelAsyncOperation メソッドの lAsyncHandle パラメータで使用されるハンドルである。

エラー コード

失敗した場合は、Err.Number に次のいずれかの値が設定される。

DPNERR_INVALIDGROUP
DPNERR_INVALIDFLAGS
DPNERR_INVALIDPLAYER


DirectPlay8Server.SendTo

指定されたプレーヤーにデータを転送する。メッセージは同期または非同期で送信することができる。

SendTo(idSend As Long, _
     buffer() As BYTE, _
    lPriority As Long, _
    lTimeOut As Long, _
    lFlags As CONST_DPNSENDFLAGS) As Long

指定項目

idSend
データを受け取るプレーヤーの識別子を指定する Long 値。
buffer()
送信するデータを記述する BYTE 型の配列。
lPriority
メッセージの優先順位。
lTimeOut
メッセージの送信を待つ時間 (ミリ秒単位)。メッセージが lTimeOut 値で送信されていない場合、メッセージは送信されない。メッセージの送信に対してタイム アウトが必要でない場合は、このパラメータを 0 に設定する。
lFlags
送信動作を記述するフラグ。CONST_DPNSENDFLAGS 列挙で定義された次の 1 つ以上のフラグを設定できる。

戻り値

この処理に対する非同期ハンドルを返す。これは、要求が非同期で処理される場合に、要求を取り消すために DirectPlay8Server.CancelAsyncOperation メソッドの lAsyncHandle パラメータで使用されるハンドルである。

エラー コード

失敗した場合は、Err.Number に次のいずれかの値が設定される。

DPNERR_INVALIDFLAGS
DPNERR_TIMEDOUT

注意

このメソッドは、受信者のメッセージ ハンドラに DirectPlay8Event.Receive メソッドを呼び出す。SendTo 要求が完了すると、送信側のメッセージ ハンドラに DirectPlay8Event.SendComplete メソッドが呼び出される。SendComplete メソッドは、DPNMSG_SEND_COMPLETE メッセージ型を保持する。要求が成功したか失敗したかは、このメッセージ型の hResultCode メンバに保持される。アプリケーションは IDirectPlay8Client、IDirectPlay8Server、または IDirectPlay8Peer で Close を呼び出す前や最終リリースをする前に、CancelAsyncOperation を呼び出して残っている Send をキャンセルすべきである。それに失敗すると予期せぬ結果が起きる。


DirectPlay8Server.SetApplicationDesc

ホストされるアプリケーションの設定を変更する。変更できるのは、いくつかの設定のみである。

SetApplicationDesc(AppDesc As DPN_APPLICATION_DESC, _
    lFlags As Long)

指定項目

AppDesc
変更するアプリケーションの設定を記述する DPN_APPLICATION_DESC 型。
lFlags
予約済み。0 に設定すること。

エラー コード

失敗した場合は、Err.Number に次のいずれかの値が設定される。

DPNERR_INVALIDFLAGS

注意

このメソッドを使って、DPN_APPLICATION_DESC 型の以下のメンバのみを変更できる。

  • lMaxPlayers
  • SessionName
  • Password


DirectPlay8Server.SetCaps

セッションの能力を設定する。

SetCaps(caps As DPN_CAPS, lFlags As Long)

指定項目

caps
現在のセッションに関する設定に使用される DPN_CAPS 型。
lFlags
予約済み。0 に設定すること。

エラー コード

失敗した場合は、Err.Number に次のいずれかの値が設定される。

DPNERR_INVALIDOBJECT
DPNERR_INVALIDPOINTER
DPNERR_INVALIDPARAM
DPNERR_UNINITIALIZED

注意

DirectPlay8Server.RegisterMessageHandler の呼び出しが成功した後に、このメソッドを呼び出す必要がある。


DirectPlay8Server.SetGroupInfo

グループ名など、グループに関連するデータのブロックを設定する。

SetGroupInfo(idGroup As Long, _
    PlayerInfo As DPN_GROUP_INFO, _
    lFlags As Long) As Long

指定項目

idGroup
データ ブロックを変更するグループの識別子を指定する Long 型。
PlayerInfo
設定するグループ データを記述する DPN_GROUP_INFO 型。
lFlags
このメソッドが処理される方法を制御するフラグ。このメソッドには次のフラグを設定できる。
DPNOP_SYNC
メソッドを同期をとりながら処理する。

戻り値

この処理に対する非同期ハンドルを返す。これは、要求が非同期で処理される場合に、要求を取り消すために DirectPlay8Server.CancelAsyncOperation メソッドの lAsyncHandle パラメータで使用されるハンドルである。

エラー コード

失敗した場合は、Err.Number に次のいずれかの値が設定される。

DPNERR_INVALIDGROUP
DPNERR_INVALIDFLAGS


DirectPlay8Server.SetServerInfo

アプリケーションとのクライアントの静的設定を設定する。アプリケーションに基本的なプレーヤー情報を転送するには、接続前にこのメソッドを呼び出す。クライアントが正しくアプリケーションに接続すると、ほかのプレーヤーはこのメソッドで取得された情報を DirectPlay8Client.GetServerInfo メソッドを呼び出して取得できる。

SetServerInfo(PlayerInfo As DPN_PLAYER_INFO) As Long

指定項目

PlayerInfo
設定するプレーヤ情報を保持する DPN_PLAYER_INFO 型。

戻り値

この処理に対する非同期ハンドルを返す。これは、要求が非同期で処理される場合に、要求を取り消すために DirectPlay8Server.CancelAsyncOperation メソッドの lAsyncHandle パラメータで使用されるハンドルである。

エラー コード

失敗した場合は、Err.Number に次のいずれかの値が設定される。

DPNERR_NOCONNECTION
DPNERR_INVALIDFLAGS
DPNERR_INVALIDPARAM

注意

DirectPlay8Server.SetClientInfo メソッドを使用すると処理に負担がかかるため、非静的情報は DirectPlay8Server.SendTo メソッドを使用して転送すること。

アプリケーションへの接続後、このメソッドを使用してクライアント情報を変更できる。接続後このメソッドが呼び出されると、DirectPlay は各プレーヤーの DirectPlay8Event.InfoNotify メソッドを呼び出して、プレーヤーにデータが更新されたことを通知する。


DirectPlay8Server.SetSPCaps

指定されたサービス プロバイダの能力を設定する。

SetSPCaps(guidSP As String, spCaps As DPN_SP_CAPS)

指定項目

guidSP
情報を設定するサービス プロバイダの GUID を指定する文字列。
spCaps
指定されたサービス プロバイダに関する情報を設定する DPN_SP_CAPS 型。

エラー コード

失敗した場合は、Err.Number に次のいずれかの値が設定される。

DPNERR_INVALIDOBJECT
DPNERR_INVALIDPOINTER
DPNERR_INVALIDPARAM
DPNERR_UNINITIALIZED

注意

DirectPlay8Server.RegisterMessageHandler の呼び出しが成功した後に、このメソッドを呼び出す必要がある。


DirectPlay8Server.UnregisterMessageHandler

現在のメッセージ ハンドラの登録を解除する。

UnRegisterMessageHandler()

注意

新しいメッセージ ハンドラを登録するには、その前にこのメソッドを呼び出す必要がある。


DirectPlayVoiceClient8

アプリケーションは、DirectPlayVoiceClient8 クラスのメソッドを使用して、音声セッションのクライアントを管理する。

DirectPlayVoiceClient8 クラスのメソッドは、以下のグループにまとめることができる。

バッファ管理 | Create3DSoundBuffer
 | Delete3DSoundBuffer
その他 | GetCaps
 | GetCompressionType
 | GetCompressionTypeCount
 | GetSoundDeviceConfig
 | GetSoundDevices
 | StartClientNotification
セッション管理 | Connect
 | Disconnect
 | GetClientConfig
 | GetSessionDesc
 | GetTransmitTargets
 | Initialize
 | SetClientConfig
 | SetCurrentSoundDevices
 | SetTransmitTargets
 | UnRegisterMessageHandler


DirectPlayVoiceClient8.Connect

クライアントを Microsoft® DirectPlay® Voice セッションに接続する。

Connect( _
    SoundDeviceConfig As DVSOUNDDEVICECONFIG, _
    ClientConfig As DVCLIENTCONFIG, _
    lFlags As Long)

指定項目

SoundDeviceConfig
サウンド デバイス構成を記述する DVSOUNDDEVICECONFIG 型。
ClientConfig
クライアントの一般的構成を記述する DVCLIENTCONFIG 型。
lFlags
次のフラグを指定できる。
DVFLAGS_SYNC
処理が完了するまでメソッドは戻らない。

エラー コード

失敗した場合は、Err.Number に次のいずれかの値が設定される。

DVERR_ALREADYPENDING
DVERR_INVALIDPARAM
DVERR_INVALIDPOINTER
DVERR_INVALIDOBJECT
DVERR_SOUNDINITFAILURE
DVERR_INVALIDFLAGS
DVERR_OUTOFMEMORY
DVERR_NOTINITIALIZED
DVERR_COMPRESSIONNOTSUPPORTED
DVERR_TIMEOUT
DVERR_INVALIDDEVICE
DVERR_SENDERROR
DVERR_INCOMPATIBLEVERSION
DVERR_TRANSPORTNOPLAYER
DVERR_TRANSPORTNOSESSION
DVERR_RUNSETUP

注意

DirectPlay Voice セッションにクライアントを接続する前にセットアップ ウィザードを呼び出し、再生とキャプチャ用に選択したサウンド デバイスをテストする必要がある。アプリケーションの起動時には、DirectPlayVoiceTest8.CheckAudioSetup を使用してオーディオ構成を確認する。このメソッドが DVERR_RUNSETUP を返す場合、指定されたサウンド構成はテストされていない。セットアップ ウィザードは構成ごとに 1 回だけ実行する必要がある。

接続がペンディング状態になっている間に DirectPlayVoiceClient8.Connect を呼び出すと、DVERR_ALREADYPENDING が返される。また、1 度に 1 つの接続のみをペンディング状態にできる。

このメソッドを呼び出す前に、指定された DirectPlay オブジェクトに対してトランスポート セッションを開始している必要がある。DirectPlayVoiceClient8.Initialize の呼び出しが成功した後に Connect メソッドを呼び出す必要がある。


DirectPlayVoiceClient8.Create3DSoundBuffer

プレーヤーまたはグループ用の 3D サウンド バッファを取得する。3D サウンド バッファ オブジェクトのメソッドを使用すると、指定したグループまたはプレーヤーから受信した音声転送の仮想 3D 位置を変更できる。

Create3DSoundBuffer(playerID As Long) _
    As DirectSound3dBuffer8

指定項目

playerID
ユーザーがバッファを保持する対象となるプレーヤーまたはグループの識別情報を指定する長整数型 (Long) の値。また、DVID_REMAINING を指定すると、ユーザー バッファがないすべてのプレーヤーまたはグループに対して 3D ユーザー バッファを作成できる。

戻り値

Microsoft® DirectPlay® Voice のメイン バッファに使用される DirectSound3dBuffer8 型を返す。

エラー コード

失敗した場合は、Err.Number に次のいずれかの値が設定される。

DVERR_INVALIDPARAM
DVERR_NOTCONNECTED
DVERR_SESSIONLOST
DVERR_ALREADYBUFFERED
DVERR_INVALIDPOINTER
DVERR_INVALIDOBJECT
DVERR_NOTINITIALIZED
DVERR_OUTOFMEMORY
DVERR_NOTALLOWED

注意

DirectPlay Voice セッションがミキシング サーバー セッションの場合、このメソッドは失敗し、DVERR_NOTALLOWED を返す。

DirectPlay Voice クライアントはバッファを使用して受信オーディオのストリーミングを行うため、3D サウンド バッファ オブジェクトのすべてのメンバ関数にアクセスできる。ただし、DirectSound3Dbuffer オブジェクトの Lock、UnLock、Play の各メソッドは使用しないこと。

個々のユーザーのバッファが不必要になるか、プレーヤーが音声セッションを離れる場合、DirectPlayVoiceClient8.Delete3DSoundBuffer を呼び出し、リソースを解放する必要がある。


DirectPlayVoiceClient8.Delete3DSoundBuffer

3D サウンド バッファ オブジェクトの排他制御を Microsoft® DirectPlay® Voice クライアント オブジェクトに返す。

Delete3DSoundBuffer(playerID As Long, _
    UserBuffer As DirectSound3dBuffer8)

指定項目

playerID
ユーザーがバッファを削除する対象となるプレーヤーまたはグループの DVID を指定する長整数型 (Long) の値。
UserBuffer
削除するユーザーバッファ。DirectPlayVoiceClient8.Create3DSoundBuffer メソッドにより取得されたユーザー バッファを指定する必要がある。

エラー コード

失敗した場合は、Err.Number に次のいずれかの値が設定される。

DVERR_INVALIDPARAM
DVERR_NOTCONNECTED
DVERR_SESSIONLOST
DVERR_ALREADYBUFFERED
DVERR_INVALIDPOINTER
DVERR_NOTBUFFERED
DVERR_INVALIDOBJECT
DVERR_NOTINITIALIZED
DVERR_NOTALLOWED

注意

DirectPlay Voice セッションがミキシング サーバー セッションの場合、このメソッドは失敗し、DVERR_NOTALLOWED を返す。


DirectPlayVoiceClient8.Disconnect

既存の DirectPlay Voice セッションから Microsoft® DirectPlay® Voice クライアントの接続を解除する。

Disconnect(lFlags As Long)

指定項目

lFlags
次のフラグを指定できる。
DVFLAGS_SYNC
処理が完了するまで戻らない。

エラー コード

失敗した場合は、Err.Number に次のいずれかの値が設定される。

DVERR_PENDING
DVERR_ALREADYPENDING
DVERR_INVALIDPARAM
DVERR_NOTCONNECTED
DVERR_INVALIDFLAGS
DVERR_CONNECTABORTING
DVERR_NOTINITIALIZED
DVERR_TIMEOUT
DVERR_SESSIONLOST

注意

このメソッドを呼び出すと、録音と再生はすべて停止する。処理中の接続は、この呼び出しにより取り消される。

DVFLAGS_SYNC フラグを設定し、同期をとってこのメソッドを呼び出した場合、Disconnect が完了するまでこのメソッドは戻らない。


DirectPlayVoiceClient8.GetCaps

Microsoft® DirectPlay® Voice の能力を取得する。

GetCaps() As DVCAPS

戻り値

DirectPlay VoiceClient8 オブジェクトの能力を保持する DVCAPS 型を返す。

エラー コード

失敗した場合は、Err.Number に次のいずれかの値が設定される。

DVERR_INVALIDPARAM
DVERR_INVALIDPOINTER


DirectPlayVoiceClient8.GetClientConfig

クライアント構成を取得する。

GetClientConfig() As DVCLIENTCONFIG

戻り値

ローカル クライアントの構成を保持する DVCLIENTCONFIG 型を返す。

エラー コード

失敗した場合は、Err.Number に次のいずれかの値が設定される。

DVERR_INVALIDPARAM
DVERR_NOTCONNECTED
DVERR_SESSIONLOST
DVERR_INVALIDPOINTER
DVERR_NOTINITIALIZED

注意

Microsoft® DirectPlay® Voice セッションで接続の確立に成功した後にのみ、このメソッドを呼び出すことができる。


DirectPlayVoiceClient8.GetCompressionType

圧縮タイプを取得する。

GetCompressionType(lIndex As Long, _
    Data As DVCOMPRESSIONINFO, _
   lFlags As Long)

指定項目

lIndex
圧縮タイプを指定する。サポートされている圧縮タイプの数は、DirectPlayVoiceClient8.GetCompressionTypeCount を呼び出して確認できる。
Data
圧縮情報を記述する DVCOMPRESSIONINFO 型。
lFlags
予約済み。0 に設定すること。

エラー コード

失敗した場合は、Err.Number に次のいずれかの値が設定される。

DVERR_INVALIDPARAM
DVERR_BUFFERTOOSMALL
DVERR_INVALIDPOINTER
DVERR_INVALIDFLAGS


DirectPlayVoiceClient8.GetCompressionTypeCount

サポートされている圧縮タイプの数を取得する。

GetCompressionTypeCount() As Long

戻り値

サポートされている圧縮タイプの数を返す。

エラー コード

失敗した場合は、Err.Number に次のいずれかの値が設定される。

DVERR_INVALIDOBJECT


DirectPlayVoiceClient8.GetSessionDesc

セッションのプロパティを取得する。

GetSessionDesc() As DVSESSIONDESC

戻り値

セッションの記述を受け取る DVSESSIONDESC 型を返す。

エラー コード

失敗した場合は、Err.Number に次のいずれかの値が設定される。

DVERR_INVALIDPARAM
DVERR_INVALIDPOINTER
DVERR_NOTCONNECTED
DVERR_SESSIONLOST
DVERR_NOTINITIALIZED

注意

このメソッドは、Microsoft® DirectPlay® Voice セッションで接続の確立に成功した後にのみ呼び出すことができる。


DirectPlayVoiceClient8.GetSoundDeviceConfig

セッションのサウンド デバイスの構成を取得する。

GetSoundDeviceConfig() As DVSOUNDDEVICECONFIG

戻り値

サウンド デバイスの構成が格納された DVSOUNDDEVICECONFIG 型を返す。

エラー コード

失敗した場合は、Err.Number に次のいずれかの値が設定される。

DVERR_INVALIDPARAM
DVERR_NOTCONNECTED
DVERR_SESSIONLOST
DVERR_INVALIDPOINTER
DVERR_NOTINITIALIZED

注意

Microsoft® DirectPlay® Voice セッションで接続の確立に成功した後にのみ、このメソッドを呼び出すことができる。


DirectPlayVoiceClient8.GetSoundDevices

現在の Microsoft® DirectSound® キャプチャ オブジェクトおよび再生オブジェクトを取得する。

GetSoundDevices( _
    DirectSoundObj As DirectSound8, _
    DirectCaptureObj As DirectSoundCapture8)

指定項目

DirectSoundObj
再生に使用される現在の DirectSound8 オブジェクト。
DirectCaptureObj
キャプチャに使用される現在の DirectSoundCapture8 オブジェクト。

エラー コード

失敗した場合は、Err.Number に次のいずれかの値が設定される。

DVERR_INVALIDPARAM


DirectPlayVoiceClient8.GetTransmitTargets

このクライアントからの音声ストリームの転送ターゲットを取得する (存在する場合)。

GetTransmitTargets(lFlags As Long) As Long()

指定項目

lFlags
予約済み。0 に設定すること。

戻り値

クライアント音声ストリームの転送ターゲットの DVID を保持する Long 値の配列を返す (存在する場合)。

エラー コード

失敗した場合は、Err.Number に次のいずれかの値が設定される。

DVERR_NOTALLOWED
DVERR_INVALIDPARAM
DVERR_INVALIDPOINTER
DVERR_BUFFERTOOSMALL
DVERR_NOTCONNECTED
DVERR_NOTINITIALIZED
DVERR_INVALIDFLAGS

注意

返される DVID はプレーヤー DVID とグループ DVID のどちらかである。


DirectPlayVoiceClient8.Initialize

DirectPlayVoiceClient8 オブジェクトを DirectPlay オブジェクトに関連付けることにより、DirectPlayVoiceClient8 オブジェクトを初期化する。

DirectPlayVoiceClient8.Connect メソッドを呼び出す前に、このメソッドの呼び出しが成功している必要がある。

Initialize(DplayObj As Unknown, lFlags As Long)

指定項目

DplayObj
この DirectPlayVoiceClient8 オブジェクトが使用する DirectPlay オブジェクトの IUnknown インターフェイスへのポインタ。
lFlags
予約済み。0 に設定すること。

エラー コード

失敗した場合は、Err.Number に次のいずれかの値が設定される。

DVERR_INVALIDPARAM
DVERR_ALREADYINITIALIZED
DVERR_INVALIDPOINTER
DVERR_TRANSPORTNOTINIT
DVERR_NOCALLBACK
DVERR_GENERIC


DirectPlayVoiceClient8.SetClientConfig

クライアント構成を設定する。

SetClientConfig(ClientConfig As DVCLIENTCONFIG)

指定項目

ClientConfig
設定する構成の記述を保持する DVCLIENTCONFIG 型。

エラー コード

失敗した場合は、Err.Number に次のいずれかの値が設定される。

DVERR_INVALIDPARAM
DVERR_INVALIDPOINTER
DVERR_INVALIDFLAGS
DVERR_NOTCONNECTED
DVERR_NOTINITIALIZED
DVERR_SESSIONLOST

注意

Microsoft® DirectPlay® Voice セッションで接続の確立に成功した後にのみ、このメソッドを呼び出すことができる。

このメソッドを呼び出すと、DVCLIENTCONFIG 型のすべてのパラメータが設定される。したがって、設定を変更しないようにするには、DirectPlayVoiceClient8.GetClientConfig を使用して、現在の構成を取得する必要がある。次に、パラメータを変更し、DirectPlayVoiceClient8.SetClientConfig を呼び出す。

セッションが半二重で実行されている場合、録音に関連する GetClientConfig メソッドのメンバは無視される。


DirectPlayVoiceClient8.SetCurrentSoundDevices

現在の Microsoft® DirectSound® キャプチャ オブジェクトおよび再生オブジェクトを設定する。

SetCurrentSoundDevices( _
    DirectSoundObj As DirectSound8, _
    DirectCaptureObj As DirectSoundCapture8)

指定項目

DirectSoundObj
再生に使用する DirectSound8 オブジェクト。
DirectCaptureObj
キャプチャに使用する DirectSoundCapture8 オブジェクト。

エラー コード

失敗した場合は、Err.Number に次のいずれかの値が設定される。

DVERR_INVALIDPARAM


DirectPlayVoiceClient8.SetTransmitTargets

ローカル クライアントから送信されるオーディオを受け取るプレーヤーまたはグループを指定する。

SetTransmitTargets(playerIDs() As Long, lFlags As Long)

指定項目

playerIDs()
音声送信を受け取るプレーヤーまたはグループの DVID を指定する Long 値の配列。
lFlags
予約済み。0 に設定すること。

エラー コード

失敗した場合は、Err.Number に次のいずれかの値が設定される。

DVERR_INVALIDPARAM
DVERR_INVALIDFLAGS
DVERR_INVALIDPOINTER
DVERR_NOTINITIALIZED
DVERR_INVALIDTARGET

注意

DVSESSION_SERVERCONTROLTARGET フラグを使用してセッションが作成された場合、サーバーだけがこのローカル クライアントにターゲットを設定できる。このメソッドを呼び出すと、DVERR_NOTALLOWED が返される。


DirectPlayVoiceClient8.StartClientNotification

DirectPlayVoiceEvent8 オブジェクトをクライアントに登録し、クライアントとサーバーにより生成されるすべてのメッセージを受信する。

StartClientNotification(event As DirectPlayVoiceEvent8)

指定項目

event
このクライアントおよびサーバーからメッセージを受け取る DirectPlayVoiceEvent8 オブジェクト。

エラー コード

失敗した場合は、Err.Number に次のいずれかの値が設定される。

DVERR_INVALIDPARAM


DirectPlayVoiceClient8.UnregisterMessageHandler

現在の DirectPlayVoiceClient8 メッセージ ハンドラの登録を解除する。

UnRegisterMessageHandler()

注意

新しいメッセージ ハンドラを登録するには、その前にこのメソッドを呼び出す必要がある。


DirectPlayVoiceEvent8

アプリケーションは、DirectPlayVoiceEvent8 クラスのメソッドを使用して、DirectPlayVoiceClient8 クラスおよび DirectPlayVoiceServer8 クラスにより生成された Microsoft® DirectPlay® イベントをキャプチャする。

注 DirectPlayVoiceEvent8 オブジェクトを実装する場合、Microsoft® Visual Basic® のフォームにこのオブジェクトのすべてのメソッドを実装する必要がある。

DirectPlayVoiceEvent8 クラスのメソッドを次に示す。

DirectPlayVoiceEvent8 メソッド | ConnectResult
 | CreateVoicePlayer
 | DeleteVoicePlayer
 | DisconnectResult
 | HostMigrated
 | InputLevel
 | OutputLevel
 | PlayerOutputLevel
 | PlayerVoiceStart
 | PlayerVoiceStop
 | RecordStart
 | RecordStop
 | SessionLost


DirectPlayVoiceEvent8.ConnectResult

DirectPlayVoiceClient8.Connect メソッドの呼び出しにより生成された接続要求が完了すると、呼び出される。

ConnectResult(ResultCode As Long)

指定項目

ResultCode
結果コードが設定される Long 値。


DirectPlayVoiceEvent8.CreateVoicePlayer

新しいプレーヤーが音声セッションに参加すると、呼び出される。

CreateVoicePlayer(playerID As Long, _
     flags As Long)

指定項目

playerID
プレーヤーの IDが設定される Long 値。
flags
プレーヤーの情報を保持するフラグ。


DirectPlayVoiceEvent8.DeleteVoicePlayer

プレーヤーが音声セッションを終了すると、呼び出される。

DeleteVoicePlayer(playerID As Long)

指定項目

playerID
プレーヤーの IDが設定される Long 値。


DirectPlayVoiceEvent8.DisconnectResult

DirectPlayVoiceClient8.Disconnect メソッドの呼び出しにより生成された接続の解除要求が完了すると、呼び出される。

DisconnectResult(ResultCode As Long)

指定項目

ResultCode
結果コードが設定される Long 値。


DirectPlayVoiceEvent8.HostMigrated

音声ホストが変更されると、呼び出される。

HostMigrated(NewHostID As Long, _
     NewServer As DirectPlayVoiceServer8)

指定項目

NewHostID
新しい音声ホストの ID が設定される長整数型 (Long) の値。
NewServer
ローカル クライアントが新しい音声セッション ホストになった場合、このメンバは新たに作成された DirectPlayVoiceServer8 オブジェクトを示す。ローカル クライアントは、このオブジェクトを使用してホスト サービスを提供できる。ローカル クライアントが新しいホストではない場合、このメンバは NULL になる。


DirectPlayVoiceEvent8.InputLevel

マイクからの入力レベルをユーザーに知らせるため、周期的に呼び出される。

InputLevel(PeakLevel As Long, _
    RecordVolume As Long)

指定項目

PeakLevel
現在のフレームのピーク レベルを表す Long 値。オーディオ ストリームの約 1/10 秒に相当する。一般に現在のフレームはリアルタイムよりも 50 ～ 200 ミリ秒遅れる。この値は 0 ～ 99 の範囲になる。0 は完全に無音、99 は可能な最大入力レベルを表す。
RecordVolume
クライアントの現在の録音ボリューム。値の範囲は -10,000 ～ 0 である。自動ゲイン制御がアクティブな場合でも、このメンバは利用できる。


DirectPlayVoiceEvent8.OutputLevel

マイクからの出力レベルをユーザーに知らせるため、周期的に呼び出される。

OutputLevel(PeakLevel As Long, _
    OutputVolume As Long)

指定項目

PeakLevel
現在のフレームのピーク レベルを表す Long 値。オーディオ ストリームの約 1/10 秒に相当する。一般に現在のフレームはリアルタイムよりも 50 ～ 200 ミリ秒遅れる。この値は 0 ～ 99 の範囲になる。0 は完全に無音、99 は可能な最大出力レベルを表す。
OutputVolume
クライアントの現在の再生ボリューム。


DirectPlayVoiceEvent8.PlayerOutputLevel

個々のプレーヤーの音声ストリームの出力レベルをユーザーに知らせるため、周期的に呼び出される。個々のプレーヤーに音声が再生されている間、このメッセージが生成される。複数のプレーヤーの音声が再生される場合、各通知期間で、プレーヤーの音声ごとに 1 つのメッセージが送信される。

PlayerOutputLevel(SourcePlayerID As Long, _
    PeakLevel As Long)

指定項目

SourcePlayerID
再生される音声のプレーヤーの ID が設定される Long 値。
PeakLevel
プレーヤーの音声ストリームのピーク出力レベルを表す整数。この値は 0 ～ 99 の範囲になる。0 は完全に無音、99 は可能な最大出力レベルを表す。


DirectPlayVoiceEvent8.PlayerVoiceStart

受信オーディオ ストリームが再生を開始すると、呼び出される。

PlayerVoiceStart(SourcePlayerID As Long)

指定項目

SourcePlayerID
音声転送が開始されるプレーヤーの ID が設定される Long 値。


DirectPlayVoiceEvent8.PlayerVoiceStop

受信オーディオ ストリームが停止すると、呼び出される。

PlayerVoiceStop(SourcePlayerID As Long)

指定項目

SourcePlayerID
音声転送が停止されるプレーヤーの ID が設定される Long 値。


DirectPlayVoiceEvent8.RecordStart

ローカル クライアントのオーディオ入力が開始されると、呼び出される。音声をアクティブにする感知レベルを超えるか、プッシュツートーク モードで有効なターゲットが指定された場合、オーディオ入力は開始される。

RecordStart(PeakVolume As Long)

指定項目

PeakVolume
送信を開始する音声をアクティブにするレベルが設定される Long 値。プッシュツートーク モードでは、この値は 0 である。


DirectPlayVoiceEvent8.RecordStop

ローカル クライアントのオーディオ入力が停止すると、呼び出される。音声をアクティブにする感知レベルに達しないか、プッシュツートーク モードでターゲットが削除された場合、オーディオ入力は停止する。

RecordStop(PeakVolume As Long)

指定項目

PeakVolume
送信を停止する音声をアクティブにするレベルが設定される Long 値。プッシュツートーク モードでは、この値は 0 である。


DirectPlayVoiceEvent8.SessionLost

音声セッションが終了すると、呼び出される。

SessionLost(ResultCode As Long)

指定項目

ResultCode
セッションが終了した理由を示す結果コードが設定される Long 値。


DirectPlayVoiceServer8

アプリケーションは、DirectPlayVoiceServer8 クラスのメソッドを使用して、音声セッションのホストを管理する。

DirectPlayVoiceServer8 クラスのメソッドは、以下のグループにまとめることができる。

その他 | GetCaps
 | GetCompressionType
 | GetCompressionTypeCount
セッション管理 | GetSessionDesc
 | GetTransmitTargets
 | Initialize
 | SetSessionDesc
 | SetTransmitTargets
 | StartServerNotification
 | StartSession
 | StopSession
 | UnregisterMessageHandler


DirectPlayVoiceServer8.GetCaps

Microsoft® DirectPlay® Voice の能力を取得する。

GetCaps() As DVCAPS

戻り値

DirectPlay VoiceClient8 オブジェクトの能力を保持する DVCAPS 型を返す。

エラー コード

失敗した場合は、Err.Number に次のいずれかの値が設定される。

DVERR_INVALIDPARAM
DVERR_INVALIDPOINTER


DirectPlayVoiceServer8.GetCompressionType

圧縮タイプを取得する。

GetCompressionType(lIndex As Long, _
    Data As DVCOMPRESSIONINFO, _
   lFlags As Long)

指定項目

lIndex
圧縮タイプを指定する。サポートされている圧縮タイプの数は、DirectPlayVoiceServer8.GetCompressionTypeCount を呼び出して確認できる。
Data
圧縮情報を記述する DVCOMPRESSIONINFO 型。
lFlags
予約済み。0 に設定すること。

エラー コード

失敗した場合は、Err.Number に次のいずれかの値が設定される。

DVERR_INVALIDPARAM
DVERR_BUFFERTOOSMALL
DVERR_INVALIDPOINTER
DVERR_INVALIDFLAGS


DirectPlayVoiceServer8.GetCompressionTypeCount

サポートされている圧縮タイプの数を取得する。

GetCompressionTypeCount() As Long

戻り値

サポートされている圧縮タイプの数を返す。

エラー コード

失敗した場合は、Err.Number に次のいずれかの値が設定される。

DVERR_INVALIDOBJECT


DirectPlayVoiceServer8.GetSessionDesc

セッションのプロパティを取得する。

GetSessionDesc() As DVSESSIONDESC

戻り値

セッションの記述を受け取る DVSESSIONDESC 型を返す。

エラー コード

失敗した場合は、Err.Number に次のいずれかの値が設定される。

DVERR_INVALIDPARAM
DVERR_INVALIDPOINTER
DVERR_NOTCONNECTED
DVERR_SESSIONLOST
DVERR_NOTINITIALIZED

注意

このメソッドは、Microsoft® DirectPlay® Voice セッションで接続の確立に成功した後にのみ呼び出すことができる。


DirectPlayVoiceServer8.GetTransmitTargets

セッションのプレーヤーに対する音声ストリームの転送ターゲットを取得する (存在する場合)。

GetTransmitTargets(playerSourceID As Long, _
    lFlags As Long) As Long()

指定項目

playerSourceID
ターゲットに送信するユーザーまたはグループの DVID を指定する長整数型 (Long) の値。
lFlags
予約済み。0 に設定すること。

戻り値

クライアントの音声ストリームの送信ターゲットの DVID を保持する Long 値の配列を返す (存在する場合)。このメソッドを呼び出す場合、この値は DirectPlayVoiceServer8.SetTransmitTargets メソッドで設定されたターゲット数と一致する必要がある。

エラー コード

失敗した場合は、Err.Number に次のいずれかの値が設定される。

DVERR_NOTALLOWED
DVERR_INVALIDPARAM
DVERR_INVALIDPOINTER
DVERR_BUFFERTOOSMALL
DVERR_NOTCONNECTED
DVERR_NOTINITIALIZED
DVERR_INVALIDFLAGS

注意

このメソッドは、DirectPlay Voice セッションの作成時に DVSESSION_SERVERCONTROLTARGET フラグが指定された場合にのみ使用できる。このフラグが指定されていない場合、メソッドは DVERR_NOTALLOWED を返す。


DirectPlayVoiceServer8.Initialize

DirectPlayVoiceServer8 オブジェクトを Microsoft® DirectPlay® オブジェクトに関連付けることで、DirectPlayVoiceClient8 オブジェクトを初期化する。

Initialize(DplayObj As Unknown, lFlags As Long)

指定項目

DplayObj
この DirectPlayVoiceServer8 オブジェクトが使用する DirectPlay オブジェクトの IUnknown インターフェイスへのポインタ。
lFlags
予約済み。0 に設定すること。

エラー コード

失敗した場合は、Err.Number に次のいずれかの値が設定される。

DVERR_INVALIDPARAM
DVERR_ALREADYINITIALIZED
DVERR_INVALIDPOINTER
DVERR_TRANSPORTNOTINIT
DVERR_NOCALLBACK
DVERR_GENERIC


DirectPlayVoiceServer8.SetSessionDesc

セッション設定を設定する。

SetSessionDesc(ClientConfig As DVSESSIONDESC)

指定項目

ClientConfig
セッションの記述を保持する DVSESSIONDESC 型。

エラー コード

失敗した場合は、Err.Number に次のいずれかの値が設定される。

DVERR_INVALIDPARAM
DVERR_NOTHOSTING
DVERR_NOTINITIALIZED
DVERR_INVALIDPOINTER
DVERR_SESSIONLOST
DVERR_INVALIDOBJECT

注意

Microsoft® DirectPlay® 音声セッションが開始されると、DVSESSIONDESC 構造体のセッション プロパティの一部は変更できない。詳細については、DVSESSIONDESC を参照すること。


DirectPlayVoiceServer8.SetTransmitTargets

クライアントからセッションの指定されたメンバへのオーディオ転送を制御する。

SetTransmitTargets(playerSourceID As Long, _
    playerTargetIDs As Long(), _
    lFlags As Long)

指定項目

playerSourceID
ターゲットが設定されるユーザーの DVID。
playerTargetIDs
音声送信を受信するプレーヤーまたはグループの DVID を指定する Long 値の配列。ターゲットを指定しない場合は、このパラメータに空の配列を渡す。すべてのプレーヤーを指定するには、DVID_ALLPLAYERS を保持する単項目の配列を作成する。
lFlags
予約済み。0 に設定すること。

エラー コード

失敗した場合は、Err.Number に次のいずれかの値が設定される。

DVERR_INVALIDPARAM
DVERR_NOTALLOWED
DVERR_INVALIDFLAGS
DVERR_INVALIDPOINTER
DVERR_NOTINITIALIZED
DVERR_INVALIDTARGET

注意

このメソッドは、DirectPlay Voice セッションの作成時に DVSESSION_SERVERCONTROLTARGET フラグが指定された場合にのみ使用できる。このフラグが指定されていない場合、メソッドは DVERR_NOTALLOWED を返す。


DirectPlayVoiceServer8.StartServerNotification

この Microsoft® DirectPlay® セッションにより生成されたメッセージのキャプチャに使用される、DirectPlayVoiceEvent8 オブジェクトを登録する。

StartServerNotification(event As DirectPlayVoiceEvent8)

指定項目

event
このクライアントおよびサーバーからメッセージを受け取る DirectPlayVoiceEvent8 オブジェクト。

エラー コード

失敗した場合は、Err.Number に次のいずれかの値が設定される。

DVERR_INVALIDPARAM


DirectPlayVoiceServer8.StartSession

実行中の DirectPlay トランスポート セッション内で初期化された Microsoft® DirectPlay® Voice セッションを開始する。このメソッドの呼び出しが成功しないと、クライアントは音声セッションへの接続を完了できない。

StartSession(SessionDesc As DVSESSIONDESC, lFlags As Long)

指定項目

SessionDesc
セッションの記述を保持する DVSESSIONDESC 型。
lFlags
予約済み。0 に設定すること。

エラー コード

失敗した場合は、Err.Number に次のいずれかの値が設定される。

DVERR_INVALIDPARAM
DVERR_ALREADYPENDING
DVERR_NOTINITIALIZED
DVERR_INVALIDOBJECT
DVERR_INVALIDPOINTER
DVERR_INVALIDFLAGS
DVERR_HOSTING

注意

このメソッドを呼び出す前に DirectPlayVoiceServer8.Initialize メソッドを呼び出す必要がある。音声セッションがピアツーピアである場合、音声セッションはセッションの任意のクライアントでホストできる。音声セッションがピアツーピアではない場合、アクティブなトランスポート セッションのホストであるトランスポート クライアントでホストする必要がある。

DVSESSIONDESC 構造体は、開始する音声セッションのタイプを保持する。音声セッションのタイプによっては、クライアントとサーバーの CPU と帯域幅の使用について、大きな影響を与えることがある。


DirectPlayVoiceServer8.StopSession

Microsoft® DirectPlay® Voice セッションを停止する。

StopSession(lFlags As Long)

指定項目

lFlags
次のフラグを設定できる。
DVFLAGS_NOHOSTMIGRATE
セッションとトランスポートの設定に関係なく、ホストは移行しない。音声セッションを完全にシャット ダウンする場合は、このフラグを使用する。

エラー コード

失敗した場合は、Err.Number に次のいずれかの値が設定される。

DVERR_INVALIDPARAM
DVERR_ALREADYPENDING
DVERR_SESSIONLOST
DVERR_NOTINITIALIZED
DVERR_NOTHOSTING
DVERR_INVALIDFLAGS
DVERR_INVALIDOBJECT

注意

別のスレッドで StopSession 要求が処理されている間にこのメソッドが呼び出された場合、DVERR_ALREADYPENDING エラー値が返される。


DirectPlayVoiceServer8.UnregisterMessageHandler

現在の DirectPlayVoiceServer8 メッセージ ハンドラの登録を解除する。

UnRegisterMessageHandler()

注意

新しいメッセージ ハンドラを登録するには、その前にこのメソッドを呼び出す必要がある。


DirectPlayVoiceTest8

アプリケーションは、DirectPlayVoiceTest8 クラスのメソッドを使用して、Microsoft® DirectPlay® Voice のオーディオ構成をテストする。

DirectPlayVoiceTest8 クラスの CheckAudioSetup メソッドを使って、オーディオ構成をチェックする。


DirectPlayVoiceTest8.CheckAudioSetup

指定されたデバイスに対してオーディオ セットアップ ウィザードを実行する。この関数は、デバイスにいくつかのテストを行い、全二重オーディオを利用できるかどうかを確認する。また、マイクが接続されており、キャプチャ デバイスで正しく動作するかどうかを確認する。

CheckAudioSetup( _
    guidPlaybackDevice As String, _
    guidCaptureDevice As String, _
    hwndOwner As Long, _
    lFlags As Long) As Long

指定項目

guidPlaybackDevice
テストする再生デバイスを識別する GUID。このパラメータに空文字列を渡した場合、Microsoft® DirectPlay® Voice は Microsoft® DirectSound® に定義されているデフォルトの音声再生デバイスをテストする。
guidCaptureDevice
テストするキャプチャ デバイスを識別する GUID。このパラメータに空文字列を渡した場合、DirectPlay® Voice は DirectSound に定義されているデフォルトの音声キャプチャ デバイスをテストする。
hwndOwner
このメソッドにより呼び出されるテスト ウィザードはモーダルである。ウィザードの親ウィンドウになるウィンドウが呼び出し元のアプリケーションにある場合、そのウィンドウへのハンドルをこのパラメータで渡す必要がある。呼び出し元アプリケーションにウィンドウがない場合、0 を渡すことができる。DVFLAGS_QUERYONLY フラグを指定した場合、このパラメータは使用されず、アプリケーションは 0 を渡すことができる。
lFlags
フラグ。次のフラグを設定できる。
DVFLAGS_QUERYONLY
オーディオ セットアップは実行されない。その代わり、メソッドはレジストリを調べ、デバイスがテストされているかどうかを確認する。デバイスがテストされていない場合、メソッドは DVERR_RUNSETUP を返す。デバイスがテストされている場合、デバイスが全二重オーディオをサポートしていれば、メソッドは DV_FULLDUPLEX を返し、デバイスが全二重オーディオをサポートしていなければ、メソッドは DV_HALFDUPLEX を返す。
DVFLAGS_ALLOWBACK
ウィザードのウェルカム ページで [戻る] ボタンが有効になる。ユーザーがウェルカム ページの [戻る] ボタンをクリックすると、ウィザードは終了し、CheckAudioSetup は DVERR_USERBACK を返す。

エラー コード

失敗した場合は、Err.Number に次のいずれかの値が設定される。

DVERR_INVALIDPARAM
DVERR_RUNSETUP

注意

このメソッドはユーザー インターフェイス (UI) の要素を含み、ダイアログ ボックスを表示する。DVFLAGS_QUERYONLY フラグを指定すると、テストは実際には実行されず、UI は起動しない。その代わり、レジストリを調べ、デバイスの以前のテスト結果を確認する。


関数

ここでは、以下の Microsoft® DirectPlay® 関数に関するリファレンス情報を提供する。これらの関数は、バイト配列の処理を簡素化するように設計されている。

  • AddDataToBuffer
  • AddStringToBuffer
  • GetDataFromBuffer
  • GetStringFromBuffer
  • NewBuffer


AddDataToBuffer

バイト配列に非文字列データを追加する。

AddDataToBuffer( _
    Buffer() As Byte, _
    lData As Any, _
    lSize As Long, _
    lOffset As Long)

パラメータ

Buffer
データが追加される Byte 配列。
lData
Buffer に追加するデータ。
lSize
lData のデータのサイズ (バイト単位)。この値を決定する最も簡単な方法は、Microsoft® Visual Basic® LenB 関数を使用することである。また、CONST_DPLAYBUFSIZE 列挙のいずれかの値を使用することもできる。
lOffset
バイト配列内で、データを追加する位置までのオフセット (バイト単位) を保持する Long 値。関数が戻ると、このパラメータに、追加されたデータの後の最初のバイトのオフセットが設定される。

注意

Buffer に渡されたバイト配列に、追加データを保持できる大きさがない場合、配列はデータを失うことなく、十分なサイズまで拡大される。


AddStringToBuffer

バイト配列に文字列を追加する。

AddStringToBuffer( _
    Buffer() As Byte, _
    StringData As String, _
    lOffset As Long)

パラメータ

Buffer
データが追加される Byte 配列。
StringData
Buffer に追加する String 値。
lOffset
バイト配列内で、データを追加する位置までのオフセット (バイト単位) を保持する Long 値。関数が戻ると、このパラメータに、追加されたデータの後の最初のバイトのオフセットが設定される。

注意

Buffer に渡されたバイト配列に、追加文字列を保持できる大きさがない場合、配列はデータを失うことなく、十分なサイズまで拡大される。


GetDataFromBuffer

バイト配列から非文字列データを取得する。

GetDataFromBuffer( _
    Buffer() As Byte, _
    lData As Any, _
    lSize As Long, _
    lOffset As Long)

パラメータ

Buffer
データが取得される Byte 配列。
lData
Buffer から取得されたデータを受け取る変数。
lSize
IData のデータのサイズ (バイト単位)。この値を決定する最も簡単な方法は、Visual Basic の LenB 関数を使用することである。また、CONST_DPLAYBUFSIZE 列挙のいずれかの値を使用することもできる。
lOffset
バイト配列内で、データが取得される位置までのオフセット (バイト単位)。関数が戻ると、このパラメータに、取得されたデータの後の最初のバイトのオフセットが設定される。


GetStringFromBuffer

バイト配列から文字列データを取得する。

GetStringFromBuffer( _
    Buffer() As Byte, _
    lOffset As Long) As String

パラメータ

Buffer
データが取得される Byte 配列。
lOffset
バイト配列内で、データが取得される位置までのオフセット (バイト単位) を保持する Long 値。関数が戻ると、このパラメータに、取得されたデータの後の最初のバイトのオフセットが設定される。

戻り値

取得した文字列を保持する String 値を返す。


NewBuffer

バイト配列を作成する。

NewBuffer( Buffer() As Byte ) As Long

パラメータ

Buffer
デフォルトのメンバ数に初期化される Byte 配列。

戻り値

配列の開始位置へのオフセットを保持する Long 値を返す。この値は常に 0 である。

注意

返される配列のデフォルトのメンバ数は 20 である。


型

ここでは、Microsoft® DirectPlay® で使用される以下の型について説明する。

  • DPL_APPLICATION_INFO
  • DPL_CONNECT_INFO
  • DPL_CONNECTION_SETTINGS
  • DPL_MESSAGE_CONNECT
  • DPL_MESSAGE_CONNECTION_SETTINGS
  • DPL_MESSAGE_RECEIVE
  • DPL_PROGRAM_DESC
  • DPN_APPLICATION_DESC
  • DPN_CAPS
  • DPN_CONNECTION_INFO
  • DPN_GROUP_INFO
  • DPN_PLAYER_INFO
  • DPN_SERVICE_PROVIDER_INFO
  • DPN_SP_CAPS
  • DPNMSG_ASYNC_OP_COMPLETE
  • DPNMSG_CONNECT_COMPLETE
  • DPNMSG_ENUM_HOSTS_QUERY
  • DPNMSG_ENUM_HOSTS_RESPONSE
  • DPNMSG_INDICATE_CONNECT
  • DPNMSG_RECEIVE
  • DPNMSG_SEND_COMPLETE
  • DVCAPS
  • DVCLIENTCONFIG
  • DVCOMPRESSIONINFO
  • DVSESSIONDESC
  • DVSOUNDDEVICECONFIG


DPL_APPLICATION_INFO

DirectPlay8LobbyClient.GetLocalProgram メソッドで返され、ロビー アプリケーションを記述する。

Type DPL_APPLICATION_INFO
    ApplicationName As String
    guidApplication As String
    lFlags As CONST_DPLSESSION
    lNumRunning As Long
    lNumWaiting As Long
End Type

メンバ

ApplicationName
ロビー アプリケーションの名前。
guidApplication
ロビー アプリケーションの GUID を指定する String。
lFlags
ロビー アプリケーションの現在の状態を記述する CONST_DPLSESSION 列挙の定数の 1 つ。
lNumRunning
アプリケーションのインスタンス数。
lNumWaiting
ロビー アプリケーションへの接続を待つクライアントの数。


DPL_CONNECT_INFO

DirectPlay8LobbyClient.ConnectApplication メソッドで、ロビー クライアントをロビー アプリケーションに接続するときの接続情報の指定に使用する。

Type DPL_CONNECT_INFO
    ConnectionSettings As DPL_CONNECTION_SETTINGS
    guidApplication As String
    lFlags As CONST_DPLCONNECT
End Type

メンバ

ConnectionSettings
この接続の設定を保持する DPL_CONNECTION_SETTINGS 型。
guidApplication
アプリケーションの GUID を指定する文字列。
lFlags
接続動作を決定する CONST_DPLCONNECT 列挙の定数の 1 つ。


DPL_CONNECTION_SETTINGS

ロビー接続の接続情報を保持する。

Type DPL_CONNECTION_SETTINGS
    AddressDeviceUrl As String
    AddressSenderUrl As String
    ApplicationDescription As DPN_APPLICATION_DESC
    lFlags As CONST_DPLCONNECTSETTINGS
    PlayerName As String
End Type

メンバ

AddressDeviceUrl
デバイスの URL に設定する String。
AddressSenderUrl
送信者の URL に設定する String。
ApplicationDescription
アプリケーションの記述を保持する DPN_APPLICATION_DESC 型。
lFlags
CONST_CONNECTSETTINGS 列挙からの値。プレーヤーがセッション ホストの場合、このメンバに DPLCONNECTSETTINGS_HOST が設定され、ホストでない場合は 0 が設定される。
PlayerName
プレーヤーの名前が設定される String 値。


DPL_MESSAGE_CONNECT

ロビー クライアントが DirectPlay8LobbyClient.ConnectApplication メソッドを使用してロビー アプリケーションに接続したとき、Microsoft® DirectPlay® によりこの型が生成される。

Type DPL_MESSAGE_CONNECT
    ConnectId As Long
    dplMsgCon As DPL_CONNECTION_SETTINGS
    LobbyConnectData() As Byte
End Type

メンバ

ConnectId
接続の識別に使用されるハンドル。このハンドルは、後で DirectPlay8LobbyClient.Send および DirectPlay8LobbyClient.ReleaseApplication の呼び出しに使用される。
dplMsgCon
接続設定を保持する DPL_CONNECTION_SETTINGS 型。
LobbyConnectData
ロビー接続データ。


DPL_MESSAGE_CONNECTION_SETTINGS

DirectPlay8LobbyEvent.ConnectionSettings メソッドで使用する。

Type DPL_MESSAGE_CONNECTION_SETTINGS
    dplConnectionSettings
    hSender As Long
End Type

メンバ

dplConnectionSettings
接続設定を記述する DPL_CONNECTION_SETTINGS 型。
hSender
このメッセージを送信した接続に対するハンドルを保持する Long 値。


DPL_MESSAGE_RECEIVE

DirectPlay8LobbyClient.Send メソッドまたは DirectPlay8LobbiedApplication.Send メソッドにより送信されたメッセージをターゲットが受け取ると、Microsoft® DirectPlay® によりこの型が生成される。

Type DPL_MESSAGE_RECEIVE
    buffer() As Byte
    lBufferSize As Long
    Sender As Long
End Type

メンバ

buffer
メッセージ データを保持する BYTE 配列。
lBufferSize
buffer メンバに保持されたメッセージ データのサイズ。
Sender
メッセージを送信したクライアントのハンドル。


DPL_PROGRAM_DESC

Microsoft® DirectPlay® ロビー アウェア アプリケーションを記述する。

Type DPL_PROGRAM_DESC
    ApplicationName As String
    CommandLine As String
    CurrentDirectory As String
    Description As String
    ExecutableFilename As String
    ExecutablePath As String
    guidApplication As String
    LauncherFilename As String
    LauncherPath As String
    lFlags As Long
End Type

メンバ

ApplicationName
アプリケーション名。
CommandLine
コマンド ライン引数。
CurrentDirectory
現在のディレクトリ。
Description
アプリケーション記述。
ExecutableFilename
アプリケーションの実行可能ファイル名。
ExecutablePath
アプリケーションの実行可能ファイルのパス。
guidApplication
アプリケーションの GUID を指定する文字列。
LauncherFilename
ランチャの実行可能ファイル名。
LauncherPath
ランチャの実行可能ファイルのパス。
lFlags
予約済み。0 に設定すること。


DPN_APPLICATION_DESC

Microsoft® DirectPlay® アプリケーションの設定を記述する。

Type DPN_APPLICATION_DESC
    guidApplication As String
    guidInstance As String
    lCurrentPlayers As Long
    lFlags As Long
    lMaxPlayers As Long
    Password As String
    SessionName As String
End Type

メンバ

guidApplication
アプリケーション GUID。
guidInstance
起動時に生成され、このアプリケーションのインスタンスを表すグローバル ユニーク識別子 (GUID)。このメンバは、DirectPlay8Peer、DirectPlay8Client、および DirectPlay8Server オブジェクトで公開される GetApplicationDesc メソッドを呼び出すときの [out] パラメータである。また、DirectPlay8Peer および DirectPlay8Client オブジェクトで公開される Connect メソッドを呼び出すときの、オプションの [in] パラメータである。DirectPlay8Server および DirectPlay8Peer オブジェクトで公開される SetApplicationDesc メソッドを呼び出すときは、NULL に設定する必要がある。DirectPlay8Server.Host または DirectPlay8Peer.Host メソッドを呼び出してこの GUID を取得することはできない。GUID は GetApplicationDesc メソッドを呼び出して取得しなければならない。
lCurrentPlayers
セッションに現在接続されているクライアントの数。
lFlags
アプリケーションの動作を記述する次のいずれかのフラグ。
DPNSESSION_CLIENT_SERVER
このタイプのセッションをクライアント/サーバー セッションと指定する。このフラグを DPNSESSION_MIGRATE_HOST と組み合わせることはできない。
DPNSESSION_NODPNSVR
DPNSVR からホストに列挙を転送しないように指定する。DPNSVR の詳細については、「DirectPlay DPNSVR アプリケーションの使い方」を参照すること。
DPNSESSION_REQUIREPASSWORD
このセッションがパスワードにより保護されるように指定する。このフラグを設定した場合、Password に有効な文字列を指定する必要がある。
DPNSESSION_MIGRATE_HOST
ピアツーピア セッションでこのフラグを設定すると、ホストの移行が可能になる。このフラグを DPNSESSION_CLIENT_SERVER と組み合わせることはできない。
lMaxPlayers
セッションで使用可能なクライアントの最大数。このメンバを 0 に設定すると、プレーヤーの数が無制限であることを示す。
Password
セッションへの接続に必要な Unicode パスワードを指定する文字列。lFlags メンバに DPNSESSION_REQUIREPASSWORD が設定されていない場合、この値は空文字列にする必要がある。
SessionName
セッションの Unicode 名を指定する文字列。

注意

IMaxPlayers、Password、および SessionName メンバは、DirectPlay8Server および DirectPlay8Peer オブジェクトで公開される Host または SetApplicationDesc メソッドを呼び出すときに設定できる。セッション中のプレーヤの現在の数より小さな値で dwMaxPlayers パラメータを設定することはできない。


DPN_CAPS

Microsoft® DirectPlay® セッションに対する一般的パラメータの設定および取得に使用される。

Type DPN_CAPS
    lConnectRetries As Long
    lConnectTimeout As Long
    lFlags As Long
    lTimeoutUntilKeepAlive As Long
End Type

メンバ

lConnectRetries
DirectPlay が接続処理中に行う接続の再試行の回数。
lConnectTimeout
DirectPlay が接続要求を再送信するまで待機する時間 (ミリ秒単位)。
lFlags
将来の使用に備えて予約されているので、0 に設定しておく。
lTimeoutUntilKeepAlive
DirectPlay が、最後にエンドポイントからパケットを受け取ってからキープ アライブ メッセージを送信するまでに待機する時間 (ミリ秒単位)。


DPN_CONNECTION_INFO

特定のエンドポイントとの接続に関する統計情報の取得に使用する。

Type DPN_CONNECTION_INFO
    lSize As Long
    lRoundTripLatencyMS As Long
    lThroughPutBPS As Long
    lPeakThroughPutBPS As Long
    lBytesSentGuaranteed As Long
    lPacketsSentGuaranteed As Long
    lBytesSentNonGuaranteed As Long
    lPacketsSentNonGuaranteed As Long
    lBytesRetried As Long
    lPacketsRetried As Long
    lBytesDropped As Long
    lPacketsDropped As Long
    lBandwidthBPS As Long
    lMessagesTransmittedHighPriority As Long
    lMessagesTimedOutHighPriority As Long
    lMessagesTransmittedNormalPriority As Long
    lMessagesTimedOutNormalPriority As Long
    lMessagesTransmittedLowPriority As Long
    lMessagesTimedOutLowPriority As Long
    lBytesReceivedGuaranteed As Long
    lPacketsReceivedGuaranteed As Long
    lBytesReceivedNonGuaranteed As Long
    lPacketsReceivedNonGuaranteed As Long
    lMessagesReceived As Long
End Type

メンバ

lSize
型のサイズを設定する Long 値。
lRoundTripLatencyMS
パケットがエンドポイントに到達し、ローカル コンピュータに戻るまでの時間の概算値 (ミリ秒単位) が設定される Long 値。ネットワークの条件が変更されるため、この値はセッション全体にわたって変動する。
lThroughPutBPS
ビット/秒 (bps) 単位で表したスループットの概算値が設定される Long 値。リンクの条件が変更されるため、この値はセッション全体にわたって変動する。
lPeakThroughPutBPS
ビット/秒 (bps) 単位で表したスループットのピーク値が設定される Long 値。リンクの条件が変更されるため、この値はセッション全体にわたって変動する。
lBytesSentGuaranteed
送信された保証付きメッセージのバイトの総数が設定される Long 値。
lPacketsSentGuaranteed
送信された保証付きパケットの数が設定される Long 値。
lBytesSentNonGuaranteed
送信された保証付きでないメッセージのバイトの総数が設定される Long 値。
lPacketsSentNonGuaranteed
送信された保証付きでないパケットの数が設定される Long 値。
lBytesRetried
再試行されたメッセージのバイトの総数が設定される Long 値。
lPacketsRetried
再試行されたパケットの数が設定される Long 値。
lBytesDropped
削除されたメッセージのバイトの総数が設定される Long 値。
lPacketsDropped
削除されたパケットの数が設定される Long 値。
lBandwidthBPS
帯域幅のバイト数/秒が設定される Long 値。
lMessagesTransmittedHighPriority
転送された優先順位の高いメッセージの数が設定される Long 値。
lMessagesTimedOutHighPriority
タイムアウトした優先順位の高いメッセージの数が設定される Long 値。
lMessagesTransmittedNormalPriority
転送された通常の優先順位のメッセージの数が設定される Long 値。
lMessagesTimedOutNormalPriority
タイムアウトした通常の優先順位のメッセージの数が設定される Long 値。
lMessagesTransmittedLowPriority
転送された優先順位の低いメッセージの数が設定される Long 値。
lMessagesTimedOutLowPriority
タイムアウトした優先順位の低いメッセージの数が設定される Long 値。
lBytesReceivedGuaranteed
受信された保証付きメッセージのバイトの総数が設定される Long 値。
lPacketsReceivedGuaranteed
受信された保証付きパケットの数が設定される Long 値。
lBytesReceivedNonGuaranteed
受信された保証付きでないメッセージのバイトの総数が設定される Long 値。
lPacketsReceivedNonGuaranteed
受信された保証付きでないパケットの数が設定される Long 値。
lMessagesReceived
受信されたメッセージの数が設定される Long 値。


DPN_GROUP_INFO

静的グループ情報を記述する。

Type DPN_GROUP_INFO
    lGroupFlags As CONST_DPNGROUPINFOFLAGS
    lInfoFlags As CONST_DPNINFO
    name As String
End Type

メンバ

lGroupFlags
グループ用に設定されたフラグを記述する CONST_DPNGROUPINFOFLAGS 列挙のいずれかの定数。
lInfoFlags
この型に保持されるデータのタイプを記述する CONST_DPNINFO 列挙のいずれかの定数。
Name
グループの名前。

注意

DirectPlay8Peer.GetGroupInfo メソッドおよび DirectPlay8Server.GetGroupInfo メソッドでこの型を使用する場合、lInfoFlags は 0 に設定する必要がある。


DPN_PLAYER_INFO

静的プレーヤー情報を記述する。

Type DPN_PLAYER_INFO
    lInfoFlags As CONST_DPNINFO
    lPlayerFlags As CONST_DPNPLAYINFOFLAGS
    name As String
End Type

メンバ

lInfoFlags
この型に保持される情報のタイプを指定する CONST_DPNINFO 列挙のいずれかの定数。
lPlayerFlags
プレーヤー用に設定されたフラグを記述する CONST_DPNPLAYINFOFLAGS 列挙のいずれかの定数。
name
プレーヤーの数。

注意

DirectPlay8Peer.GetPeerInfo メソッドおよび DirectPlay8Server.GetClientInfo メソッドでこの構造体を使用する場合、lInfoFlags は 0 に設定する必要がある。


DPN_SERVICE_PROVIDER_INFO

特定のサービス プロバイダの情報を列挙する場合に使用する。

Type DPN_SERVICE_PROVIDER_INFO
    GUID As String
    lFlags As Long
    name As String
End Type

メンバ

GUID
サービス プロバイダの GUID。
lFlags
予約済み。0 に設定すること。
name
サービス プロバイダの名前。


DPN_SP_CAPS

サービス プロバイダ用のパラメータの設定と取得に使用する。

Type DPN_SP_CAPS
    lBuffersPerThread As Long
    lDefaultEnumCount As Long
    lDefaultEnumRetryInterval As Long
    lDefaultEnumTimeout As Long
    lFlags As Long
    lMaxEnumPayloadSize As Long
    lNumThreads As Long
    lSystemBufferSizeAs Long
End Type

メンバ

lBuffersPerThread
各 DirectPlay スレッドに割り当てる未処理の受信バッファの数。受信バッファの数を増加した場合、DirectPlay はオペレーティング システム バッファからより多くのデータを引き出すことができる。ただし、アプリケーションの処理速度がデータの到着する速度に追いつかない場合は、遅延時間を延長することもできる。
lDefaultEnumCount
デフォルトの列挙カウントを指定する Long 値。
lDefaultEnumRetryInterval
デフォルトの再試行間隔 (ミリ秒単位) を指定する Long 値。
lDefaultEnumTimeout
デフォルトの列挙タイムアウト値 (ミリ秒単位) を指定する Long 値。
lFlags
以下のフラグを組み合わせることができる Long 値。
DPNSPCAPS_SUPPORTSALLADAPTERS
サービス プロバイダは、システムに存在するすべてのアダプタでサポートされている。
DPNSPCAPS_SUPPORTSBROADCAST
IP および IPX アプリケーションで、十分なアドレス情報が提供されていない場合、サービス プロバイダがある要素を全要素にコピーしてゲームを検索できる機能がある。
DPNSPCAPS_SUPPORTSDPNSRV
Dpnsvr.exe は使用する SP のポートの共有を提供する。現在、このフラグは IP と IPX においてのみ利用できる。DPNSVR の詳細については、「DirectPlay DPNSVR アプリケーションの使い方」を参照すること。
lMaxEnumPayloadSize
プレイロード情報の最大サイズを指定する Long 値で、DirectPlay8Event.EnumHostQuery および DirectPlay8Event.EnumHostQuery メソッドに付随する型の ResponseData メンバに送信できる。
lNumThreads
サービス プロバイダがサービスするネットワーク要求に対して使用するスレッドの数。デフォルト値は、システムのプロセッサ数を考慮したアルゴリズムに基づく。大部分のアプリケーションでは、この値を変更する必要はない。

プロセスでサービス プロバイダがアクティブになった後は、この値を増加することしかできない。この値を減少しても効果がない。設定はプロセス全体に有効である。つまり、現在の Microsoft® DirectPlay® オブジェクトおよびプロセスのほかの DirectPlay オブジェクトに適用される。

lSystemBufferSizeAs
オペレーティング システム バッファのサイズ。このバッファは、アプリケーションの処理速度がデータの到着する速度に追いつかないとき、通信デバイスからのデータを保持する。このバッファの目的は、突然に大量のデータを受け取った場合、または受信スレッドが瞬間的にストールされた場合に、データの損失を防ぐことである。アプリケーションが受信データを適切な速度で処理できない場合、lSystemBufferSize を増加すると遅延時間が長くなることがある。lSystemBufferSize を 0 に設定すると、オペレーティング システム バッファをなくすことができる。ただし、これを行うと、受信したデータを到着後すぐに処理できない場合に、データが失われるおそれがある。


DPNMSG_ASYNC_OP_COMPLETE

DirectPlay8Event.AsyncOpComplete メソッドの dpnotify パラメータで使用される。非同期処理が完了すると、Microsoft® DirectPlay® によりこの型が生成される。

Type DPNMSG_ASYNC_OP_COMPLETE
    AsyncOpHandle As Long
    hResultCode As Long
End Type

メンバ

AsyncOpHandle
非同期処理のハンドルを指定する Long 値。
hResultCode
非同期処理の結果を指定する Long 値。


DPNMSG_CONNECT_COMPLETE

DirectPlay8Event.ConnectComplete メソッドの dpnotify パラメータで使用する。接続要求が完了すると、Microsoft® DirectPlay® によりこの型が生成される。

Type DPNMSG_CONNECT_COMPLETE
    AsyncOpHandle As Long
    hResultCode As Long
    ReplyData() as Byte
End Type

メンバ

AsyncOpHandle
非同期処理のハンドルを指定する Long 値。
hResultCode
接続要求の結果を指定する Long 値。
ReplyData
ホストまたはサーバーによって返される接続データを保持する Byte 配列。


DPNMSG_ENUM_HOSTS_QUERY

DirectPlay8Event.EnumHostsQuery メソッドの dpnotify パラメータで使用する。プレーヤーがホストの列挙を要求すると、Microsoft® DirectPlay® によりこの型が生成される。

Type DPNMSG_ENUM_HOSTS_QUERY
    AddressDeviceUrl As String
    AddressSenderUrl As String
    lMaxResponseDataSize As Long
    ReceivedData() As Byte
    ResponseData() As Byte
End Type

メンバ

AddressDeviceUrl
デバイスの URL を保持する String 値。
AddressSenderUrl
送信者の URL を保持する String 値。
lMaxResponseDataSize
応答データ ブロックのサイズを指定する Long 値。
ReceivedData
列挙から受信した値。
ResponseData
列挙要求への応答を保持するデータ ブロック。


DPNMSG_ENUM_HOSTS_RESPONSE

DirectPlay8Event.EnumHostsResponse メソッドの dpnotify パラメータで使用する。ホストが列挙要求に応じて情報を提供すると、Microsoft® DirectPlay® によりこの型が生成される。

Type DPNMSG_ENUM_HOSTS_RESPONSE
    AddressDeviceUrl As String
    AddressSenderUrl As String
    ApplicationDescription As DPN_APPLICATION_DESC
    lRoundTripLatencyMS As Long
    ResponseData As Byte
End Type

メンバ

AddressDeviceUrl
デバイスのアドレスの URL を指定する String。
AddressSenderUrl
受信者のアドレスの URL を指定する String。
ApplicationDescription
アプリケーションを記述する DPN_APPLICATION_DESC 型。
lRoundTripLatencyMS
ラウンド トリップ遅延時間 (ミリ秒単位)。
ResponseData
列挙からの応答データ。


DPNMSG_INDICATE_CONNECT

DirectPlay8Event.IndicateConnect メソッドの dpnotify パラメータで使用する。プレーヤーがセッションへの接続を要求すると、Microsoft® DirectPlay® によりこの型が生成される。

Type DPNMSG_INDICATE_CONNECT
    AddressDeviceUrl As String
    AddressPlayerUrl As String
    UserData() As Byte
End Type

メンバ

AddressDeviceUrl
デバイスのアドレスの URL を指定する String。
AddressSenderUrl
送信者のアドレスの URL を指定する String。
UserData
接続プレーヤーのデータ。


DPNMSG_RECEIVE

DirectPlay8Event.Receive メソッドの dpnotify パラメータで使用する。メッセージが受け取られると、Microsoft® DirectPlay® によりこの型が生成される。

Type DPNMSG_RECEIVE
    idSender As Long
    iDataSize As Long
    ReceivedData() As Byte
End Type

メンバ

idSender
メッセージ送信者の識別子を指定する長整数型 (Long) の値。
iDataSize
ReceivedData メンバ内のバイト数を指定する Long 値。バイト配列はゼロから始まるため、配列の上限は IDataSize-1 となる。
ReceivedData
送信されたメッセージ データを保持する Byte 配列。


DPNMSG_SEND_COMPLETE

DirectPlay8Event.SendComplete メソッドの dpnotify パラメータで使用する。受信側がメッセージを受け取ると、Microsoft® DirectPlay® によりこの型が生成される。

Type DPNMSG_SEND_COMPLETE
    AsyncOpHandle As Long
    hResultCode As Long
    lSendTime As Long
End Type

メンバ

AsyncOpHandle
非同期処理のハンドルを指定する Long 値。
hResultCode
メッセージ送信の成功または失敗を指定する長整数型 (Long) の値。
lSendTime
送信呼び出しから終了するまでの時間 (ミリ秒単位)。


DPNMSG_TERMINATE_SESSION

DirectPlay8Event.TerminateSession メソッドで使用する。

Type DPNMSG_TERMINATE_SESSION
    hResultCode As Long
    TerminateData() As Byte
End Type

メンバ

hResultCode
セッションが終了した理由を指定する Long 値。セッションがピアツーピアで、ホストが DirectPlay8Peer.TerminateSession を呼び出した場合、このメンバには DPNERR_HOSTTERMINATEDSESSION が設定される。ホストが Close を呼び出してセッションが終了した場合、またはホストが応答を停止した場合、hResultCode に DPNERR_CONNECTIONLOST が設定される。
TerminateData
終了データ。hResultCode に DPNERR_HOSTTERMINATEDSESSION が設定された場合、TerminateData は、DirectPlay8Peer.TerminateSession の UserData パラメータによってホストが渡したデータ ブロックをポイントする。hResultCode に DPNERR_CONNECTIONLOST が設定された場合、TerminateData は空になる。


DVCAPS

Microsoft® DirectPlay® Voice クライアント オブジェクトの能力を記述する。

Type DVCAPS
    lFlags As Long
End Type

メンバ

lFlags
予約済み。0 に設定すること。


DVCLIENTCONFIG

クライアントの実行時パラメータを制御する。この型は、パラメータの初期状態を設定するために、 DirectPlayVoiceClient8.Connect の呼び出しに使用される。接続の確立後、この型を取得するには、DirectPlayVoiceClient8.GetClientConfig を呼び出す。この型を設定するには、DirectPlayVoiceClient8.SetClientConfig を使用する。

Type DVCLIENTCONFIG
    lBufferAggressiveness As CONST_DVBUFFERAGGRESSIVENESS
    lBufferQuality As CONST_DVBUFFERQUALITY
    lFlags As CONST_DVCLIENTCONFIGENUM
    lNotifyPeriod As Long
    lPlaybackVolume As Long
    lRecordVolume As Long
    lThreshold As CONST_DVTHRESHOLD
End Type

メンバ

lBufferAggressiveness
適応バッファリング アルゴリズムのバッファの即応性の程度を指定する CONST_DVBUFFERAGGRESSIVENESS 列挙の定数の 1 つ。
lBufferQuality
適応バッファリング アルゴリズムのバッファ品質を指定する CONST_DVBUFFERQUALITY 列挙の定数の 1 つ。大部分のアプリケーションでは、DVBUFFERQUALITY_DEFAULT に設定する。DVBUFFERQUALITY_MIN から DVBUFFERQUALITY_MAX までの任意の値に設定できる。一般に、値が大きいほど音声の質は高くなるが、遅延時間は長くなる。値が小さいほど遅延時間は短くなるが、質は低下する。
lFlags
CONST_DVCLIENTCONFIGENUM 列挙のフラグの組み合わせ。
lNotifyPeriod
DVMSGID_OUTPUTLEVEL メッセージと DVMSGID_INPUTLEVEL メッセージ (セッションが全二重である場合) を受け取る頻度を指定する。この値を 0 に設定した場合、メッセージは無効になる。メッセージ間の間隔をミリ秒単位で指定する。DVNOTIFYPERIOD_MINPERIOD を指定すると、メッセージ間で可能な最小時間が設定される。
lPlaybackVolume
設定する再生のボリュームを指定する。このボリュームを調整すると、メイン バッファとすべての 3D サウンド バッファが調整される。このメンバに対する有効な値については、DirectSoundPrimaryBuffer8.SetVolume メソッドを参照すること。DVPLAYBACKVOLUME_DEFAULT を指定すると、ほとんどの状況に適したデフォルト値 (フル ボリューム) を使用できる。
lRecordVolume
設定する録音のボリュームを指定する。このメンバに対する有効な値については、DirectSoundPrimaryBuffer8.SetVolume メソッドを参照すること。

自動ゲイン制御が有効になっている場合、この値を DVRECORDVOLUME_LAST に設定できる。この場合、システムは、自動ゲイン制御アルゴリズムで決まった現在のボリュームを使用する。DVRECORDVOLUME_LAST 以外の値を指定して自動ゲイン制御に組み合わせた場合、指定した値でアルゴリズムが再開する。

DirectPlayVoiceClient8.GetClientConfig を呼び出すと、この値に現在の録音ボリュームが格納される。Microsoft® DirectPlay Voice® では、録音ボリュームを調整するとき、マイクのボリューム (カード用のマイクのボリュームが存在する場合) およびマスタ録音ボリューム (カードに存在する場合) を調整する。マイクのボリュームとマスタ録音ボリュームがどちらも存在しない場合、DirectPlay Voice は録音ボリュームを調整できない。

lThreshold
CONST_DVTHRESHOLD 列挙の定数の 1 つ。lFlags メンバに DVCLIENTCONFIG_MANUALVOICEACTIVATED フラグを指定した場合に音声転送を開始する入力レベルを指定する。このフラグを指定した場合、DVTHRESHOLD_MIN から DVTHRESHOLD_MAX までの任意の値を指定できる。また、DVTHRESHOLD_DEFAULT を設定すると、デフォルト値を使用できる。

この型の lFlags メンバに DVCLIENTCONFIG_MANUALVOICEACTIVATED または DVCLIENTCONFIG_AUTOVOICEACTIVATED を指定していない場合 (プッシュツートーク モードを示す)、この値は DVTHRESHOLD_UNUSED に指定する必要がある。


DVCOMPRESSIONINFO

Microsoft® DirectPlay® Voice の特定の圧縮タイプの属性を記述する。

Type DVCOMPRESSIONINFO
    guidType As String
    lFlags As Long
    lMaxBitsPerSecond As Long
    strDescription As String
    strName As String
End Type

メンバ

guidType
DirectPlay Voice がこの圧縮タイプの識別に使用する GUID を指定する文字列型 (String) の値。
lFlags
将来の使用に備えて予約されているので、0 に設定しておく。
lMaxBitsPerSecond
CODEC で主張されている 1 秒あたりの最大ビット数。
strDescription
CODEC の記述。
strName
CODEC を記述する名前。


DVSESSIONDESC

Microsoft® DirectPlay® Voice サーバーの必要なセッション設定または現在のセッション設定を記述する。音声セッション ホストは、この型を使用してセッションを設定する。また、セッション ホストとクライアントはこの型を使用して、現在のセッションに関する情報を取得する。lFlags、lSessionType、および guidCT の各メンバは、ホストが音声セッションを開始するときにのみ設定できる。ホストはいつでもバッファ設定を変更できる。

Type DVSESSIONDESC
    guidCT As String
    lBufferAggressiveness As CONST_DVBUFFERAGGRESSIVENESS
    lBufferQuality As CONST_DVBUFFERQUALITY
    lFlags As CONST_DVSESSION
    lSessionType As CONST_DVSESSIONTYPE
End Type

メンバ

guidCT
セッションの圧縮タイプの GUID を指定する文字列型 (String) の値。
lBufferAggressiveness
バッファの即応性の程度を指定する CONST_DVBUFFERAGGRESSIVENESS 列挙の定数の 1 つ。このメンバは、ミキシング セッション以外のセッション タイプでは使用しない。ミキシング セッション以外のすべてのセッションでは、このメンバを DVBUFFERAGGRESIVENESS_DEFAULT に設定する。

DVBUFFERAGGRESIVENESS _MIN から DVBUFFERAGGRESIVENESS _MAX までの値が使用できる。また、このメンバは次の値にも設定できる。

DVBUFFERAGGRESIVENESS_DEFAULT
この値を指定すると、システムのデフォルト値が使用される。デフォルト値は、レジストリ エントリを使用して調整できる。また、コントロール パネルからも設定できる。
lBufferQuality
バッファの品質設定を指定する CONST_DVBUFFERQUALITY 列挙の定数の 1 つ。このメンバは、ミキシング セッション以外のセッション タイプでは使用しない。ミキシング セッション以外のすべてのセッションでは、このメンバを DVBUFFERQUALITY_DEFAULT に設定する。

DVBUFFERQUALITY_MIN から DVBUFFERQUALITY_MAX までの値が使用できる。また、このメンバは次の値にも設定できる。

DVBUFFERQUALITY_DEFAULT
この値を指定すると、システムのデフォルト値が使用される。デフォルト値は、レジストリ エントリを使用して調整できる。また、コントロール パネルの [サウンド] と [マルチメディア] からも設定できる。
lFlags
CONST_DVSESSION 列挙のフラグの組み合わせ。
lSessionType
実行する DirectPlay Voice セッションのタイプを指定する CONST_DVSESSIONTYPE 列挙のフラグの 1 つ。クライアント/サーバー セッションでは、DVSESSIONTYPE_PEER フラグは利用できない。ほかのすべてのフラグはすべてのセッション タイプに有効である。


DVSOUNDDEVICECONFIG

サウンド デバイス構成に関する情報の設定と取得に使用する。一度接続が確立すると、値は変更できない。接続の確立後、DirectPlayVoiceClient8.GetSoundDeviceConfig を呼び出すと、現在のサウンド デバイス設定を取得できる。

Type DVSOUNDDEVICECONFIG
    guidCaptureDevice As String
    guidPlaybackDevice As String
    hwndAppWindow As Long
    lFlags As CONST_DVSOUNDEFFECT
    lMainBufferFlags As CONST_DSBPLAYFLAGS
    lMainBufferPriority As Long
    MainSoundBuffer As DirectSoundSecondaryBuffer8
End Type

メンバ

guidCaptureDevice
DirectPlayVoiceClient8.Connect メソッドでこの型を使用する場合、キャプチャに使用するデバイスの GUID をこのメンバに指定する。

DirectPlayVoiceClient8.GetSoundDeviceConfig メソッドでこの型を使用する場合、キャプチャに使用する実際のデバイスの GUID がこのメンバに保持される。

guidPlaybackDevice
DirectPlayVoiceClient8.Connect メソッドでこの型を使用する場合、再生に使用するデバイスの GUID をこのメンバに指定する。

DirectPlayVoiceClient8.GetSoundDeviceConfig メソッドでこの型を使用する場合、再生に使用する実際のデバイスの GUID がこのメンバに保持される。

hwndAppWindow
サウンド再生のフォーカスの決定に使用されるウィンドウのハンドルに設定する必要がある。Microsoft® DirectSound® のフォーカスの詳細については、DirectSound8.SetCooperativeLevel を参照すること。フォーカスに使用するウィンドウがない場合、GetDesktopWindowHandle を使用してデスクトップ ウィンドウを使用する。
lFlags
CONST_DVSOUNDEFFECT 列挙のフラグの組み合わせ。
lMainBufferFlags
バッファの再生方法を指定する CONST_DSBPLAYFLAGS 列挙のフラグ値。
lMainBufferPriority
メイン バッファに対して Play を呼び出すと、DirectSoundSecondaryBuffer8.Play メソッドの dwPriority パラメータに直接渡される。
MainSoundBuffer
Microsoft DirectPlay® Voice のメイン バッファの作成に使用する DirectSoundSecondaryBuffer8 オブジェクト。このパラメータには、NULL か、またはユーザーが作成した DirectSound バッファのいずれかを指定できる。このメンバに NULL を設定すると、DirectPlay Voice はメイン ボイス バッファ用のバッファを作成する。ここでバッファを指定した場合、DirectPlay Voice はこのバッファをメインの音声バッファとして使用する。
  • バッファは、22 Khz、16 ビット、モノラル フォーマットでなければならない。
  • バッファの長さは 1 秒以上でなければならない。
  • バッファは、DSBCAPS_GETCURRENTPOSITION2 および DSBCAPS_CTRL3D フラグを使って作成されていなければならない。
  • バッファは、プライマリ バッファであってはならない。
  • バッファは、DirectPlay に渡されるときに再生中であってはならない。
  • バッファは、DirectPlay に渡されるときにロックされていてはならなない。


列挙

Microsoft® DirectPlay® では、Microsoft® Visual Basic® のステートメント補完機能を利用するために、列挙を使って定数をグループ化する。DirectPlay で使用される列挙型を次に示す。

  • CONST_DPLAYBUFSIZE
  • CONST_DPLCONNECT
  • CONST_DPLSESSION
  • CONST_DPNCANCELFLAGS
  • CONST_DPNENUMCLIENTGROUPFLAGS
  • CONST_DPNERR
  • CONST_DPNGROUPINFOFLAGS
  • CONST_DPNINFO
  • CONST_DPNLOBBY
  • CONST_DPNMESSAGEID
  • CONST_DPNOPERATIONS
  • CONST_DPNPLAYERGROUPFLAGS
  • CONST_DPNPLAYINFOFLAGS
  • CONST_DPNSENDFLAGS
  • CONST_DPNSESSIONFLAGS
  • CONST_DPNSPCAPS
  • CONST_DPNWAITTIME
  • CONST_DVBUFFERAGGRESSIVENESS
  • CONST_DVBUFFERQUALITY
  • CONST_DVCLIENTCONFIGENUM
  • CONST_DVERR
  • CONST_DVFLAGS
  • CONST_DVMESSAGE
  • CONST_DVNOTIFY
  • CONST_DVPLAYBACKVOLUME
  • CONST_DVSESSION
  • CONST_DVSESSIONTYPE
  • CONST_DVSOUNDEFFECT
  • CONST_DVTHRESHOLD


CONST_DPLAYBUFSIZE

バッファで使用するデータ型を指定する。

Enum CONST_DPLAYBUFSIZE
    SIZE_BOOLEAN = 2
    SIZE_BYTE = 1
    SIZE_CURRENCY = 8
    SIZE_DATE = 8
    SIZE_DECIMAL = 14
    SIZE_DOUBLE = 8
    SIZE_INTEGER = 2
    SIZE_LONG = 4
    SIZE_SINGLE = 4
End Enum

定数

SIZE_BOOLEAN
ブール変数のサイズ (バイト単位)。
SIZE_BYTE
BYTE 変数のサイズ (バイト単位)。
SIZE_CURRENCY
CURRENCY 変数のサイズ (バイト単位)。
SIZE_DATE
DATE 変数のサイズ (バイト単位)。
SIZE_DECIMAL
DECIMAL 変数のサイズ (バイト単位)。
SIZE_DOUBLE
DOUBLE 変数のサイズ (バイト単位)。
SIZE_INTEGER
INTEGER 変数のサイズ (バイト単位)。
SIZE_LONG
LONG 変数のサイズ (バイト単位)。
SIZE_SINGLE
SINGLE 変数のサイズ (バイト単位)。


CONST_DPLCONNECT

DirectPlay8LobbyClient.ConnectApplication メソッドの lFlags パラメータで接続動作の判定に使用する。

Enum CONST_DPLCONNECT
    DPLCONNECT_LAUNCHNEW = 1
    DPLCONNECT_LAUNCHNOTFOUND = 2
End Enum

定数

DPLCONNECT_LAUNCHNEW
アプリケーションの新しいインスタンスを起動する。
DPLCONNECT_LAUNCHNOTFOUND
起動設定を指定できるアプリケーションが実行されていない場合にだけ、アプリケーションの新しいインスタンスを起動する。


CONST_CONNECTSETTINGS

DPL_CONNECTION_SETTINGS 型で使用する。

Enum CONST_CONNECTSETTINGS
    DPLCONNECTSETTINGS_HOST = 1
End Enum

定数

DPLCONNECTSETTINGS_HOST
ユーザーのプレーヤーがセッション ホストである。


CONST_DPLSESSION

DirectPlay8LobbiedApplication.UpdateStatus メソッドの lStatus パラメータで使用され、ロビー クライアントとロビー アプリケーション間の接続が現在どのような状態にあるかを設定する。

Enum CONST_DPLSESSION
    DPLSESSION_CONNECTED = 1
    DPLSESSION_COULDNOTCONNECT = 2
    DPLSESSION_DISCONNECTED = 3
    DPLSESSION_HOSTMIGRATED = 5
    DPLSESSION_HOSTMIGRATEDHERE = 6
    DPLSESSION_TERMINATED = 4
End Enum

定数

DPLSESSION_CONNECTED
ロビー アプリケーションが現在セッションに接続されている。
DPLSESSION_COULDNOTCONNECT
ロビー アプリケーションがセッションに接続できない。
DPLSESSION_DISCONNECTED
ロビー アプリケーションが現在セッションから接続解除されている。
DPLSESSION_HOSTMIGRATED
ピアツーピア セッションのホストが移行された。ローカル クライアントは新しいホストではない。
DPLSESSION_HOSTMIGRATEDHERE
ピアツーピア セッションのホストが移行された。ローカル クライアントが新しいホストである。
DPLSESSION_TERMINATED
セッション ホストとロビー アプリケーションとの間の接続は終了した。


CONST_DPNCANCELFLAGS

DirectPlay8Client.CancelAsyncOperation、DirectPlay8Server.CancelAsyncOperation、および DirectPlay8Peer.CancelAsyncOperation の各メソッドの lFlags パラメータで使用され、取り消す非同期処理のタイプを指定する。

Enum CONST_DPNCANCELFLAGS
    DPNCANCEL_ALL_OPERATIONS = 32768 (&H8000)
    DPNCANCEL_CONNECT = 1
    DPNCANCEL_ENUM = 2
    DPNCANCEL_SEND = 4
End Enum

定数

DPNCANCEL_ALL_OPERATIONS
すべての非同期要求を取り消す。
DPNCANCEL_CONNECT
非同期 Connect 要求を取り消す。
DPNCANCEL_ENUM
すべての非同期 EnumHosts 要求を取り消す。EnumHosts メソッドから返されたハンドルを指定すると、単一の EnumHosts 要求を取り消すことができる。
DPNCANCEL_SEND
非同期 Send 要求を取り消す。


CONST_DPNENUMCLIENTGROUPFLAGS

DirectPlay8Peer.GetCountClientsAndGroups メソッドおよび DirectPlay8Server.GetCountClientsAndGroups メソッドの lFlags パラメータで使用され、どのようなタイプの列挙を返すかを決定する。

Enum CONST_DPNENUMCLIENTGROUPFLAGS
    DPNENUM_ALL = 17 (&H11)
    DPNENUM_GROUP_MULTICAST = 32 (&H20)
    DPNENUM_GROUPS = 16 (&H10)
    DPNENUM_PLAYERS = 1
End Enum

定数

DPNENUM_ALL
すべてのグループとプレーヤーの数を返す。
DPNENUM_GROUP_MULTICAST
マルチキャスト グループの数を返す。
DPNENUM_GROUPS
グループの数を返す。
DPNENUM_PLAYERS
プレーヤーの数を返す。


CONST_DPNERR

Microsoft® DirectPlay® のエラー値を保持する。詳細については、「エラー コード」を参照すること。


CONST_DPNGROUPINFOFLAGS

グループの設定を記述する。この列挙は、DPN_GROUP_INFO 型の lGroupFlags メンバで使用される。

Enum CONST_DPNGROUPINFOFLAGS
    DPNGROUP_AUTODESTRUCT = 1
End Enum

定数

DPNGROUP_AUTODESTRUCT
グループの作成者がグループを離れると、自動的にグループを破棄する。


CONST_DPNINFO

グループおよびプレーヤーの情報に関するメソッドで設定または取得を行う情報のタイプを指定するときに使用する。この列挙は、DPN_GROUP_INFO 型と DPN_PLAYER_INFO 型の lInfoFlags メンバで使用される。

Enum CONST_DPNINFO
    DPNINFO_DATA = 2
    DPNINFO_NAME = 1
End Enum

定数

DPNINFO_DATA
情報はプレーヤーまたはグループのデータ セットである。
DPNINFO_NAME
情報はプレーヤーまたはグループの名前である。


CONST_DPNLOBBY

DirectPlay8Client.RegisterLobby メソッドの lFlags パラメータで使用する。アプリケーションを登録するか登録解除することを示す、次の値のいずれかを設定する。

Enum CONST_DPNLOBBY
    DPNLOBBY_REGISTER = 1
    DPNLOBBY_UNREGISTER = 2
End Enum

定数

DPNLOBBY_REGISTER
アプリケーションをロビーに登録する。
DPNLOBBY_UNREGISTER
ロビーに登録したアプリケーションの登録を解除する。


CONST_DPNMESSAGEID

DirectPlay8Event クラスのメソッドによって使用されるメッセージ識別フラグを格納する。詳細については、「DirectPlay8Event.AddRemovePlayerGroup」メソッドおよび「DirectPlay8Event.InfoNotify」メソッドを参照すること。

Enum CONST_DPNMESSAGEID
    DPN_MSGID_ADD_PLAYER_TO_GROUP = -65528 (&HFFFF0008)
    DPN_MSGID_APPLICATION_DESC = -65526 (&HFFFF000A)
    DPN_MSGID_ASYNC_OP_COMPLETE = -65533 (&HFFFF0003)
    DPN_MSGID_CLIENT_INFO = -65524 (&HFFFF000C)
    DPN_MSGID_CONNECT_COMPLETE = -65520 (&HFFFF0010)
    DPN_MSGID_CREATE_GROUP = -65530 (&HFFFF0006)
    DPN_MSGID_CREATE_PLAYER = -65529 (&HFFFF0007)
    DPN_MSGID_DESTROY_GROUP = -65528 (&HFFFF0007)
    DPN_MSGID_DESTROY_PLAYER = -65527 (&HFFFF0005)
    DPN_MSGID_ENUM_HOSTS_QUERY = -65516 (&HFFFF0014)
    DPN_MSGID_ENUM_HOSTS_RESPONSE = -65515 (&HFFFF0015)
    DPN_MSGID_GROUP_INFO = -65522 (&HFFFF000E)
    DPN_MSGID_HOST_MIGRATE =  -65523 (&HFFFF000D)
    DPN_MSGID_INDICATE_CONNECT = -65521 (&HFFFF000F)
    DPN_MSGID_INDICATED_CONNECT_ABORTED = -65521 (&HFFFF000F)
    DPN_MSGID_PEER_INFO = -65525 (&HFFFF000B)
    DPN_MSGID_RECEIVE = -65535 (&HFFFF0001)
    DPN_MSGID_REMOVE_PLAYER_FROM_GROUP = -65518 (&HFFFF0012)
    DPN_MSGID_RETURN_BUFFER = -65517 (&HFFFF0013)
    DPN_MSGID_SEND_COMPLETE = -65534 (&HFFFF0002)
    DPN_MSGID_SERVER_INFO = -65523 (&HFFFF000D)
    DPN_MSGID_TERMINATE_SESSION = -65514 (&HFFFF0016)
End Enum


CONST_DPNOPERATIONS

DirectPlay8Client クラスのメソッドによって使用されるフラグのセットを格納する。詳細については、各メソッドのリファレンス情報を参照すること。

Enum CONST_DPNOPERATIONS
    DPNADDPLAYERTOGROUP_SYNC =  -2147483648 (&H80000000)
    DPNCONNECT_SYNC = -2147483648 (&H80000000)
    DPNCREATEGROUP_SYNC = -2147483648 (&H80000000)
    DPNDESTROYGROUP_SYNC =  -2147483648 (&H80000000)
    DPNENUMHOSTS_SYNC =  -2147483648 (&H80000000)
    DPNHOST_OKTOQUERYFORADDRESSING = 1
    DPNOP_SYNC =  -2147483648 (&H80000000)
    DPNREMOVEPLAYERFROMGROUP_SYNC =  -2147483648 (&H80000000)
    DPNSETCLIENTINFO_SYNC =  -2147483648 (&H80000000)
    DPNSETGROUPINFO_SYNC =  -2147483648 (&H80000000)
    DPNSETPEERINFO_SYNC =  -2147483648 (&H80000000)
    DPNSETSERVERINFO_SYNC =  -2147483648 (&H80000000)
End Enum


CONST_DPNPLAYERGROUPFLAGS

DirectPlay8Server.SendTo メソッドおよび DirectPlay8Peer.SendTo メソッドで使用する。

Enum CONST_DPNPLAYERGROUPFLAGS
    DPNID_ALL_PLAYERS_GROUP = 0
End Enum

定数

DPNID_ALL_PLAYERS_GROUP
セッションのすべてのプレーヤーにメッセージを送信する。


CONST_DPNPLAYINFOFLAGS

DPN_PLAYER_INFO 構造体の lPlayerFlags メンバで使用され、プレーヤーがホスト プレーヤーかローカル プレーヤーかを決定する。

Enum CONST_DPNPLAYINFOFLAGS
    DPNPLAYER_HOST = 4
    DPNPLAYER_LOCAL = 2
End Enum

定数

DPNPLAYER_HOST
これは、ローカル プレーヤーの情報である。
DPNPLAYER_LOCAL
このプレーヤーはアプリケーションのホストである。


CONST_DPNSENDFLAGS

DirectPlay8Client.Send メソッド、DirectPlay8Server.SendTo メソッド、および DirectPlay8Peer.SendTo メソッドでメッセージの送信方法を制御するときに設定できるフラグを格納する。

Enum CONST_DPNSENDFLAGS
    DPNSEND_COMPLETEONPROCESS = 4
    DPNSEND_GUARANTEED = 8
    DPNSEND_NOCOMPLETE = 1
    DPNSEND_NOCOPY = 2
    DPNSEND_NOLOOPBACK = 32 (&H20)
    DPNSEND_NONSEQUENTIAL = 16 (&H10)
    DPNSEND_PRIORITY_HIGH = 128 (&H80)
    DPNSEND_PRIORITY_LOW = 64 (&H40)
    DPNSEND_SYNC = -2147483648 (&H80000000)
End Enum

定数

DPNSEND_COMPLETEONPROCESS
このメッセージがターゲットに配信され、ターゲットのメッセージ ハンドラがメッセージの受信を示すとき、メッセージ ハンドラに DirectPlay8Event.SendComplete メソッドを呼び出す。このフラグが設定された場合は、余分な内部メッセージのオーバーヘッドがあり、メッセージの送信処理が著しく低下することがある。このフラグを設定する場合は、DPNSEND_GUARANTEED も設定する必要がある。
DPNSEND_GUARANTEED
保証された配信方法により、メッセージを送信する。
DPNSEND_NOCOMPLETE
送信者のメッセージ ハンドラで DirectPlay8Event.SendComplete メソッドを呼び出してはならない。このフラグが設定された場合は、余分な内部メッセージのオーバーヘッドがあり、メッセージの送信処理が著しく低下する。このフラグを DPNSEND_NOCOPY と組み合わせることはできない。
DPNSEND_NOCOPY
buffer() パラメータ タイプのデータを使用し、内部コピーを行わない。データを送信する方法としてはより効率的な場合がある。しかし、受信側がメッセージを処理する前に、送信側がメッセージを変更できるため、堅牢ではなくなる。このフラグを DPNSEND_NOCOMPLETE または DPNSEND_GUARANTEED と組み合わせることはできない。
DPNSEND_NOLOOPBACK
自分自身にメッセージを送信している場合は、メッセージ ハンドラに DirectPlay8Event.Receive メソッドを呼び出してはならない。このフラグは、セッション全体にある要素を全要素にコピーする場合、または参加しているグループにメッセージを送信するときに有用である。
DPNSEND_NONSEQUENTIAL
メッセージを受信順にターゲット アプリケーションに配信する。このフラグを設定しない場合、メッセージは送信順にターゲット アプリケーションに配信される。したがって、順序どおりでないメッセージは、欠落しているメッセージが到着するまでバッファに格納する必要がある。
DPNSEND_PRIORITY_HIGH
メッセージの優先順位を高く設定する。
DPNSEND_PRIORITY_LOW
メッセージの優先順位を低く設定する。
DPNSEND_SYNC
同期をとって SendTo 要求を処理する。


CONST_DPNGETSENDQUEUEINFO

DirectPlay8Client.GetSendQueueInfo の lFlags パラメータで使用する。次のいずれかのフラグを設定すると、メソッドはすべてのキューの合計ではなく関連する送信キューだけの情報を返す。

Enum CONST_DPNGETSENDQUEUEINFO
    DPNGETSENDQUEUEINFO_PRIORITY_HIGH = 2
    DPNGETSENDQUEUEINFO_PRIORITY_LOW = 4
    DPNGETSENDQUEUEINFO_PRIORITY_NORMAL = 1
End Enum

定数

DPNGETSENDQUEUEINFO_PRIORITY_HIGH
優先順位の高いキューの情報を返す。
DPNGETSENDQUEUEINFO_PRIORITY_LOW
優先順位の低いキューの情報を返す。
DPNGETSENDQUEUEINFO_PRIORITY_NORMAL
通常の優先順位を持つキューの情報を返す。


CONST_DPNSESSIONFLAGS

DPN_APPLICATION_DESC 型の lFlags メンバで使用し、セッションのタイプを指定する。

Enum CONST_DPNSESSIONFLAGS
    DPNSESSION_CLIENT_SERVER = 1
    DPNSESSION_MIGRATE_HOST = 4
    DPNSESSION_NODPNSVR = 64 (&H40)
    DPNSESSION_REQUIREPASSWORD = 128 (&H80)
End Enum

定数

DPNSESSION_CLIENT_SERVER
このタイプのセッションをクライアント/サーバー セッションと指定する。このフラグを DPNSESSION_MIGRATE_HOST と組み合わせることはできない。
DPNSESSION_MIGRATE_HOST
ホストの移行を可能にする。このフラグはピアツーピア セッションで使用する。このフラグを DPNSESSION_CLIENT_SERVER と組み合わせることはできない。
DPNSESSION_NODPNSVR
DPNSVR からホストに列挙を転送しないように指定する。
DPNSESSION_REQUIREPASSWORD
このセッションがパスワードにより保護されるように指定する。このフラグを設定した場合、DPN_APPLICATION_DESC 型の Password メンバは有効な文字列にする必要がある。


CONST_DPNSPCAPS

DPN_SP_CAPS 型で使用する。

Enum CONST_DPNSPCAPS
    DPNSPCAPS_SUPPORTSALLADAPTERS = 4
    DPNSPCAPS_SUPPORTSBROADCAST = 2
    DPNSPCAPS_SUPPORTSDPNSRV = 1
End Enum

定数

DPNSPCAPS_SUPPORTSALLADAPTERS
サービス プロバイダは、システム上に存在するすべてのアダプタ上でサポートされる。
DPNSPCAPS_SUPPORTSBROADCAST
IP および IPX アプリケーションでは、十分なアドレッシング情報が渡されていない場合、サービス プロバイダには、ある要素を全要素にコピーしてゲームを検索できる機能がある。
DPNSPCAPS_SUPPORTSDPNSRV
DPNSVR.EXE は、指定された SP のポート共有を提供する。現在、このフラグは IP と IPX においてのみ利用できる。


CONST_DPNWAITTIME

DirectPlay8Client.EnumHosts および DirectPlay8Peer.EnumHosts メソッドで使用する。

Enum CONST_DPNWAITTIME
    INFINITE = -1 (&HFFFFFFFF)
End Enum

定数

INFINITE
列挙が取り消されるまで待機する。


CONST_DVBUFFERAGGRESSIVENESS

DVCLIENTCONFIG 型の lBufferAggressiveness メンバで使用されるフラグを保持する。大部分のアプリケーションでは、DVBUFFERAGGRESSIVENESS_DEFAULT に設定できる。また、DVBUFFERAGGRESSIVENESS_MIN から DVBUFFERAGGRESSIVENESS_MAX までの任意の値に設定できる。一般に、値が大きいほど適応バッファリングは状況変化への対応が速くなる。値が小さいほど、適応バッファリングは状況変化への対応が遅くなる。

Enum CONST_DVBUFFERAGGRESSIVENESS
    DVBUFFERAGGRESSIVENESS_DEFAULT = 0
    DVBUFFERAGGRESSIVENESS_MAX = 100 (&H64)
    DVBUFFERAGGRESSIVENESS_MIN = 1
End Enum

定数

DVBUFFERAGGRESSIVENESS_DEFAULT
バッファの即応性のデフォルト値。
DVBUFFERAGGRESSIVENESS_MAX
バッファの即応性の最大値。
DVBUFFERAGGRESSIVENESS_MIN
バッファの即応性の最小値。


CONST_DVBUFFERQUALITY

DVCLIENTCONFIG 型の lBufferQuality メンバで使用されるフラグを保持する。大部分のアプリケーションでは、DVBUFFERQUALITY_DEFAULT に設定する。DVBUFFERQUALITY_MIN から DVBUFFERQUALITY_MAX までの任意の値に設定できる。一般に、値が大きいほど音声の質は高くなるが、遅延時間は長くなる。値が小さいほど遅延時間は短くなるが、質は低下する。

Enum CONST_DVBUFFERQUALITY
    DVBUFFERQUALITY_DEFAULT = 0
    DVBUFFERQUALITY_MAX = 100 (&H64)
    DVBUFFERQUALITY_MIN = 1
End Enum

定数

DVBUFFERQUALITY_DEFAULT
バッファの品質のデフォルト値。
DVBUFFERQUALITY_MAX
バッファの品質の最大値。
DVBUFFERQUALITY_MIN
バッファの品質の最小値。


CONST_DVCLIENTCONFIGENUM

DVCLIENTCONFIG 型の lFlags メンバで使用され、音声伝送動作を制御する。

Enum CONST_DVCLIENTCONFIGENUM
    DVCLIENTCONFIG_AUTORECORDVOLUME = 8
    DVCLIENTCONFIG_AUTOVOICEACTIVATED = 32 (&H20)
    DVCLIENTCONFIG_ECHOSUPPRESSION = 134217728 (&H8000000)
    DVCLIENTCONFIG_MANUALVOICEACTIVATED = 4
    DVCLIENTCONFIG_MUTEGLOBAL = 16 (&H10)
    DVCLIENTCONFIG_PLAYBACKMUTE = 2
    DVCLIENTCONFIG_RECORDMUTE = 1
End Enum

定数

DVCLIENTCONFIG_AUTORECORDVOLUME
自動ゲイン制御をアクティブにする。Microsoft® DirectPlay® Voice では、自動ゲイン制御を使用して、サウンド カードでハードウェア入力ボリュームを自動調整し、入力レベルを最適にする。現在の入力ボリュームを調べるには、DirectPlayVoiceClient8.GetClientConfig を呼び出した後に lRecordVolume メンバを調べる。
DVCLIENTCONFIG_AUTOVOICEACTIVATED
転送制御システムを自動音声をアクティブにするモードにする。このモードでは、音声をアクティブにする感度はシステムによって自動的に決定される。入力レベルは、入力信号に合わせて自動的に調整される。大部分のアプリケーションでは、この設定を使用する。このフラグと DVCLIENTCONFIG_MANUALVOICEACTIVATED フラグは互いに排他的である。
DVCLIENTCONFIG_ECHOSUPPRESSION
エコー抑制モードをアクティブにする。このモードは、外部スピーカと高感度マイクによる構成で発生するエコーを減少させる。リモート プレーヤーの音声はローカル スピーカで再生されるが、マイクは自動的にミュートされる。ローカル プレーヤーが発信する場合、ローカル入力が停止するまで、リモート プレーヤーの音声の再生はバッファに格納される。ローカル入力が停止した後、再生が再開する。
DVCLIENTCONFIG_MANUALVOICEACTIVATED
転送制御システムを手動音声をアクティブにするモードにする。このモードでは、入力レベルが DVCLIENTCONFIG 型の lThreshold メンバに指定されたレベルを超えると、音声の転送が開始される。入力レベルが指定レベルより下になると、転送は停止する。このフラグは DVCLIENTCONFIG_AUTOVOICEACTIVATED フラグと互いに排他的である。
DVCLIENTCONFIG_MUTEGLOBAL
メイン サウンド バッファの再生をミュートする。DirectPlayVoiceClient8.Create3DSoundBuffer を呼び出して作成されたサウンド バッファのみが再生される。
DVCLIENTCONFIG_PLAYBACKMUTE
すべての DirectPlay Voice 出力の再生をミュートし、再生を停止する。また、受信パケットの圧縮の復元も停止するため、CPU の使用量が減少する。このフラグが指定されている間、パケットは実質的に廃棄される。
DVCLIENTCONFIG_RECORDMUTE
マイクからの入力をミュートし、録音を停止する。また、圧縮も停止するため、CPU の使用量は減少する。

上記のフラグに加え、次のフラグのいずれか一方を設定するか、どちらも指定しないことで、転送方法を制御できる。

DVCLIENTCONFIG_MANUALVOICEACTIVATED または DVCLIENTCONFIG_AUTOVOICEACTIVATED のどちらも指定しない場合、システムはプッシュツートーク モードで動作する。プッシュツートーク モードでは、有効なターゲットが指定されている限り、マイクからの入力は転送される。NULL ターゲットが設定されるか、現在のターゲットがセッションを離れるか、または現在のターゲットが破棄された場合、音声転送は停止する。


CONST_DVERR

Microsoft® DirectPlay® Voice のエラー値を保持する。詳細については、「エラー コード」を参照すること。


CONST_DVFLAGS

さまざまな Microsoft® DirectPlay® 音声関連メソッドで使用する。

Enum CONST_DVFLAGS
    DVFLAGS_ALLOWBACK = 16 (&H10)
    DVFLAGS_NOHOSTMIGRATE = 8
    DVFLAGS_QUERYONLY = 2
    DVFLAGS_SYNC = 1
End Enum

定数

DVFLAGS_ALLOWBACK
ウィザードのウェルカム ページにある [Back] ボタンを有効にする。ユーザーがウェルカム ページの [Back] ボタンをクリックすると、ウィザードは終了し、CheckAudioSetup は DVERR_USERBACK を返す。
DVFLAGS_NOHOSTMIGRATE
セッションとトランスポートの設定に関係なく、音声ホストは移行しない。音声セッションを完全にシャット ダウンする場合は、このフラグを使用する。
DVFLAGS_QUERYONLY
オーディオ セットアップは実行されない。その代わり、メソッドはレジストリを調べ、デバイスがテストされているかどうかを確認する。デバイスがテストされていない場合、メソッドは DVERR_RUNSETUP を返す。デバイスがテストされている場合、デバイスが全二重オーディオをサポートしていれば、メソッドは DV_FULLDUPLEX を返し、デバイスが全二重オーディオをサポートしていなければ、メソッドは DV_HALFDUPLEX を返す。
DVFLAGS_SYNC
処理が完了するまで戻らない。


CONST_DVMESSAGE

使用しない。

Enum CONST_DVMESSAGE
    DVID_ALLPLAYERS = 0
    DVID_NOTARGET = -1 (&HFFFFFFFF)
    DVID_REMAINING = -1 (&HFFFFFFFF)
    DVID_SERVERPLAYER = 1
    DVID_SYS = 0
    DVMSGID_BASE = 0
    DVMSGID_CONNECTRESULT = 8
    DVMSGID_CREATEVOICEPLAYER = 1
    DVMSGID_DELETEVOICEPLAYER = 2
    DVMSGID_DISCONNECTRESULT = 9
    DVMSGID_HOSTMIGRATED = 14
    DVMSGID_INPUTLEVEL = 12
    DVMSGID_MAXBASE = 16 (&H10)
    DVMSGID_MINBASE = 1
    DVMSGID_OUTPUTLEVEL = 13
    DVMSGID_PLAYEROUTPUTLEVEL = 16 (&H10)
    DVMSGID_PLAYERVOICESTART = 4
    DVMSGID_PLAYERVOICESTOP = 5
    DVMSGID_RECORDSTART = 6
    DVMSGID_RECORDSTOP = 7
    DVMSGID_SESSIONLOST = 3
    DVMSGID_SETTARGET = 15
    DVMSGID_STARTSESSIONRESULT = 10
    DVMSGID_STOPSESSIONRESULT = 11
End Enum


CONST_DVNOTIFY

DVCLIENTCONFIG 型で使用される。

Enum CONST_DVNOTIFY
    DVNOTIFYPERIOD_MINPERIOD = 20 (&H14)
End Enum

定数

DVNOTIFYPERIOD_MINPERIOD
メッセージ間で可能な最小時間を指定する。


CONST_DVPLAYBACKVOLUME

DVCLIENTCONFIG 型で使用する。

Enum CONST_DVPLAYBACKVOLUME
    DVPLAYBACKVOLUME_DEFAULT = 0
End Enum

定数

CONST_DVPLAYBACKVOLUME
ほとんどの状況に該当するデフォルト値を使用する。


CONST_DVSESSION

DVSESSIONDESC 型の lFlags メンバで使用し、セッションの動作を制御する。

Enum CONST_DVSESSION
    DVSESSION_NOHOSTMIGRATION = 1
    DVSESSION_SERVERCONTROLTARGET = 2
End Enum

定数

DVSESSION_NOHOSTMIGRATION
トランスポートの設定に関係なく、音声ホストは移行しない。このフラグを指定しない場合、トランスポートのサポートがあれば、音声ホストは移行する。
DVSESSION_SERVERCONTROLTARGET
サーバー プレーヤーのみがクライアントの音声のターゲットを制御できる。サーバー プレーヤーがこのフラグを指定しない場合、クライアントのみが音声のターゲットを制御できる。このフラグは、マルチキャスト セッションおよびミキシング セッションでのみ指定できる。


CONST_DVSESSIONTYPE

DVSESSIONDESC 型の lSessionType メンバで使用され、実行する Microsoft® DirectPlay® Voice セッションのタイプを指定する。クライアント/サーバー セッションでは、DVSESSIONTYPE_PEER フラグは利用できない。ほかのすべてのフラグはすべてのセッション タイプに有効である。

Type CONST_DVSESSIONTYPE
    DVSESSIONTYPE_ECHO = 4
    DVSESSIONTYPE_MIXING = 2
    DVSESSIONTYPE_MULTICAST = 3
    DVSESSIONTYPE_PEER = 1
End Type

定数

DVSESSIONTYPE_ECHO
音声メッセージをプレーヤーにエコーバックする。
DVSESSIONTYPE_MIXING
音声セッションがミキシング サーバーを使用する。この処理モードでは、すべての音声メッセージはサーバーに送信される。サーバーはミキシングし、単一のミキシング済みストリームを各クライアントに転送する。サーバーの帯域幅と CPU の使用量が増加する代わりに、クライアントの帯域幅と CPU の使用量は大きく減少する。
DVSESSIONTYPE_MULTICAST
音声メッセージはセッション ホストを経由してルーティングされる。サーバーの帯域幅を使用する代わりにクライアントの帯域幅は節約できる。セッション ホストが高速接続している場合にのみ、このオプションは役立つ。
DVSESSIONTYPE_PEER
音声メッセージをプレーヤー間で直接送信する。


CONST_DVSOUNDEFFECT

DVSOUNDDEVICECONFIG 型の lFlags メンバで使用し、サウンドの動作を制御する。

Enum CONST_DVSOUNDEFFECT
    DVSOUNDCONFIG_AUTOSELECT = 2
    DVSOUNDCONFIG_HALFDUPLEX = 4
    DVSOUNDCONFIG_NOFOCUS = 536870912 (&H20000000)
    DVSOUNDCONFIG_NORECVOLAVAILABLE = 16 (&H10)
    DVSOUNDCONFIG_NORMALMODE = 1
    DVSOUNDCONFIG_SETCONVERSIONQUALITY = 8
    DVSOUNDCONFIG_STRICTFOCUS = 1073741824 (&H40000000)
End Enum

定数

DVSOUNDCONFIG_AUTOSELECT
Microsoft® DirectPlay® Voice は、指定された録音デバイス用のミキサでマイク ラインを自動的に選択 (またはミュート解除) しようとする。
DVSOUNDCONFIG_HALFDUPLEX
DirectPlay Voice を半二重モードで初期化する。半二重モードでは録音は行われない。全二重モードでサウンド システムの初期化が失敗した場合、システムによってこのフラグが設定される。
DVSOUNDCONFIG_NOFOCUS
このリリースでは有効ではない。
DVSOUNDCONFIG_NORECVOLAVAILABLE
録音ボリュームを変更できないことを示す。
DVSOUNDCONFIG_NORMALMODE
DirectPlay Voice は Microsoft DirectSound® の通常モードを使用して DirectSound オブジェクトを初期化する。このフラグを指定しない場合、DirectSound オブジェクトは DirectSound の優先モードで初期化される。詳細については、DirectSound8.SetCooperativeLevel の説明を参照すること。
DVSOUNDCONFIG_SETCONVERSIONQUALITY
CPU の使用量が増加する代わりに、高品質のオーディオを使用できる。
DVSOUNDCONFIG_STRICTFOCUS
このリリースでは有効ではない。


CONST_DVTHRESHOLD

DVCLIENTCONFIG 型の lThreshold メンバで使用される。lFlags メンバに DVCLIENTCONFIG_MANUALVOICEACTIVATED フラグが指定された場合、音声転送の開始に使用される入力レベルを指定する。このフラグを指定した場合、DVTHRESHOLD_MIN から DVTHRESHOLD_MAX までの任意の値を指定できる。また、DVTHRESHOLD_DEFAULT を設定すると、デフォルト値を使用できる。

この構造体の lFlags メンバに DVCLIENTCONFIG_MANUALVOICEACTIVATED または DVCLIENTCONFIG_AUTOVOICEACTIVATED を指定していない場合 (プッシュツートーク モードを示す)、この値は DVTHRESHOLD_UNUSED に指定する必要がある。

Enum CONST_DVTHRESHOLD
    DVTHRESHOLD_DEFAULT = -1 (&HFFFFFFFF)
    DVTHRESHOLD_MAX = 99 (&H63)
    DVTHRESHOLD_MIN = 0
    DVTHRESHOLD_UNUSED = -2 (&HFFFFFFFE)
End Enum

定数

DVTHRESHOLD_DEFAULT
デフォルトのしきい値。
DVTHRESHOLD_MAX
しきい値の最大値。
DVTHRESHOLD_MIN
しきい値の最小値。
DVTHRESHOLD_UNUSED
プッシュツートーク モードの場合に設定する必要がある。


エラー コード

次の表は、Microsoft® DirectPlay® のメソッドと関数が返す可能性があるエラー コードの一覧を示している。エラーは負の値で表され、組み合わせて使用されることはない。

各メソッドまたは関数が返す可能性がある値のリストについては、個々の記述を参照すること。本文中のエラー コードの一覧は、必然的に不完全になっている。たとえば、すべての DirectPlay メソッドは DPERR_OUTOFMEMORY を返すことができるが、本文中では、このエラー コードはそのメソッドの戻り値としては明示されていない。

DPNERR_ABORTED
処理は、完了する前にキャンセルされた。
DPNERR_ADDRESSING
指定されたアドレスが無効である。
DPNERR_ALREADYCONNECTED
オブジェクトはすでにセッションに接続されている。
DPNERR_ALREADYCLOSING
セッションでの Close 呼び出しが複数回行われた。
DPNERR_ALREADYDISCONNECTING
クライアントはすでにセッションから接続解除している。
DPNERR_ALREADYINITIALIZED
オブジェクトは既に初期化されている。
DPNERR_ALREADYREGISTERED
メッセージ ハンドラは既に登録されている。新しいメッセージ ハンドラを登録するには、現在登録されているメッセージ ハンドラをあらかじめ登録解除する必要がある。
DPNERR_BUFFERTOOSMALL
指定されたバッファが小さすぎて、要求されたデータを格納できない。
DPNERR_CANNOTCANCEL
処理を取り消すことができなかった。
DPNERR_CANTCREATEGROUP
新しいグループを作成できない。
DPNERR_CANTCREATEPLAYER
新しいプレーヤーを作成できない。
DPNERR_CANTLAUNCHAPPLICATION
ロビーは指定されたアプリケーションを起動できない。
DPNERR_CONNECTING
メソッドはネットワークへの接続処理中である。
DPNERR_CONNECTIONLOST
データの送信中に、サービス プロバイダの接続がリセットされた。
DPNERR_DOESNOTEXIST
要求された要素はアドレスの一部ではない。
DPNERR_EXCEPTION
要求を処理しているときに例外が発生した。
DPNERR_GENERIC
定義されていないエラー条件が発生した。
DPNERR_GROUPNOTEMPTY
指定されたグループが空ではない。
DPNERR_HOSTING
DPNERR_HOSTREJECTEDCONNECTION
接続要求は拒否された。詳細については、DPNMSG_CONNECT_COMPLETE 型の ReplyData メンバを参照すること。
DPNERR_HOSTTERMINATEDSESSION
ホストがセッションを終了した。
DPNERR_INCOMPLETEADDRESS
指定されたアドレスが不完全である。
DPNERR_INVALIDADDRESSFORMAT
アドレス形式が無効である。
DPNERR_INVALIDAPPLICATION
アプリケーションに指定された GUID が無効である。
DPNERR_INVALIDCOMMAND
指定されたコマンドが無効である。
DPNERR_INVALIDFLAGS
このメソッドに渡されたフラグは無効である。
DPNERR_INVALIDGROUP
グループ ID が、このゲーム セッションに対する有効なグループ ID として認識されていない。
DPNERR_INVALIDHANDLE
指定されたハンドルが無効である。
DPNERR_INVALIDINSTANCE
アプリケーションのインスタンスの GUID が無効である。
DPNERR_INVALIDINTERFACE
インターフェイス パラメータが無効である。接続元プレーヤーがクライアント/サーバー ゲームのクライアントまたはピアツーピア ゲームのピアではなかった場合、接続要求にこの値が返される。
DPNERR_INVALIDLOCALADDRESS
ローカル コンピュータまたはアダプタのアドレスが無効である。
DPNERR_INVALIDOBJECT
DirectPlay オブジェクトのポインタは無効である。
DPNERR_INVALIDPARAM
メソッドに渡された 1 つ以上のパラメータが無効である。
DPNERR_INVALIDPASSWORD
パスワードを要求するセッションに参加するときに、無効なパスワードが提供された。
DPNERR_INVALIDPLAYER
プレーヤー ID が、このゲーム セッションに対する有効なプレーヤー ID として認識されていない。
DPNERR_INVALIDPOINTER
パラメータとして指定されたポインタが無効である。
DPNERR_INVALIDPRIORITY
指定された優先順位が、指定可能な範囲内 (0 ～ 65535) ではない。
DPNERR_INVALIDSTRING
パラメータとして指定された文字列が無効である。
DPNERR_INVALIDREMOTEADDRESS
指定されたリモート アドレスが無効である。
DPNERR_INVALIDURL
指定された文字列が無効な DirectPlay URL である。
DPNERR_INVALIDVERSION
DirectPlay の無効なバージョンに接続しようとした。
DPNERR_NOCAPS
DirectPlay が使用する通信リンクが、この関数に対応していない。
DPNERR_NOCONNECTION
通信リンクが確立されていない。
DPNERR_NOHOSTPLAYER
現在、セッションのホストとして機能するプレーヤーがない。
DPNERR_NOINTERFACE
インターフェイスがサポートされていない。
DPNERR_NORESPONSE
指定されたターゲットから応答がない。
DPNERR_NOTALLOWED
オブジェクトは読み取り専用である。このオブジェクトに対してこの機能は使用できない。
DPNERR_NOTHOST
クライアントがホスト以外のコンピュータに接続しようとした。また、ホスト以外のコンピュータがアプリケーションの記述を設定しようとした場合に、このエラー値が返されることがある。
DPNERR_OUTOFMEMORY
要求された処理を実行するために必要な量のメモリが存在しない。
DPNERR_PENDING
エラーではない。この戻り値は、非同期処理で、キューへの設定が成功するところまで処理が進んだことを示す。
DPNERR_PLAYERLOST
プレーヤーがセッションへの接続を失った。
DPNERR_SENDTOOLARGE
バッファが大きすぎた。
DPNERR_SESSIONFULL
セッションに割り当てられているプレーヤーの最大数に達したため、ホストまたはサーバーへの接続要求が失敗した。
DPNERR_TIMEDOUT
時間切れのため、処理が完了できなかった。
DPNERR_UNINITIALIZED
要求されたオブジェクトが初期化されていない。
DPNERR_UNSUPPORTED
関数または機能が、この実装またはサービス プロバイダでは利用できない。
DPNERR_USERCANCEL
ユーザーは処理を取り消した。
DV_OK
要求は正しく完了した。
DV_FULLDUPLEX
サウンド カードは全二重処理が可能である。
DV_HALFDUPLEX
サウンド カードは半二重モードでしか動作しない。
DVERR_BUFFERTOOSMALL
指定されたバッファが小さすぎて、要求されたデータを格納できない。
DVERR_EXCEPTION
要求を処理しているときに例外が発生した。
DVERR_GENERIC
定義されていないエラー条件が発生した。
DVERR_INVALIDFLAGS
このメソッドに渡されたフラグは無効である。
DVERR_INVALIDOBJECT
DirectPlay オブジェクトのポインタは無効である。
DVERR_INVALIDPARAM
メソッドに渡された 1 つ以上のパラメータが無効である。
DVERR_INVALIDPLAYER
プレーヤー ID が、このゲーム セッションに対する有効なプレーヤー ID として認識されていない。
DVERR_INVALIDGROUP
グループ ID が、このゲーム セッションに対する有効なグループ ID として認識されていない。
DVERR_INVALIDHANDLE
指定されたハンドルが無効である。
DVERR_OUTOFMEMORY
要求された処理を実行するために必要な量のメモリが存在しない。
DVERR_PENDING
エラーではない。この戻り値は、非同期処理で、キューへの設定が成功するところまで処理が進んだことを示す。
DVERR_NOTSUPPORTED
処理がサポートされていない。
DVERR_NOINTERFACE
指定されたインターフェイスがサポートされていない。このエラーは、指定したインターフェイスを公開していない以前のバージョンの DirectX を使用していることを示している。
DVERR_SESSIONLOST
トランスポートがセッションへの接続を失った。
DVERR_NOVOICESESSION
指定されたセッションは音声セッションではない。
DVERR_CONNECTIONLOST
音声セッションへの接続が失われた。
DVERR_NOTINITIALIZED
このメソッドを呼び出す前に、DirectPlayVoiceClient8.Initialize メソッドまたは DirectPlayVoiceServer8.Initialize メソッドを呼び出す必要がある。
DVERR_CONNECTED
DirectPlay Voice オブジェクトが接続されている。
DVERR_NOTCONNECTED
DirectPlay Voice オブジェクトが接続されていない。
DVERR_CONNECTABORTING
接続解除中。
DVERR_NOTALLOWED
オブジェクトには、この処理を実行する権限がない。
DVERR_INVALIDTARGET
指定されたターゲットは、この音声セッションの有効なプレーヤー ID またはグループ ID ではない。
DVERR_TRANSPORTNOTHOST
オブジェクトは音声セッションのホストではない。
DVERR_COMPRESSIONNOTSUPPORTED
指定された圧縮タイプがローカル コンピュータでサポートされていない。
DVERR_ALREADYPENDING
このタイプの非同期呼び出しは既にペンディング状態になっている。
DVERR_ALREADYINITIALIZED
オブジェクトは既に初期化されている。
DVERR_SOUNDINITFAILURE
サウンド カードの初期化に失敗した。
DVERR_TIMEOUT
指定された時間内に処理を実行できなかった。
DVERR_CONNECTABORTED
接続処理は、完了する前にキャンセルされた。
DVERR_NO3DSOUND
ローカル コンピュータでは 3D サウンドをサポートしていない。
DVERR_ALREADYBUFFERED
指定された ID には既にユーザー バッファがある。
DVERR_NOTBUFFERED
指定された ID にはユーザー バッファがない。
DVERR_HOSTING
オブジェクトはセッションのホストである。
DVERR_NOTHOSTING
オブジェクトはセッションのホストではない。
DVERR_INVALIDDEVICE
指定されたデバイスが無効である。
DVERR_RECORDSYSTEMERROR
録音システムにエラーが発生した。
DVERR_PLAYBACKSYSTEMERROR
再生システムにエラーが発生した。
DVERR_SENDERROR
データの送信中にエラーが発生した。
DVERR_USERCANCEL
ユーザーは処理を取り消した。
DVERR_UNKNOWN
不明なエラーが発生した。
DVERR_RUNSETUP
指定されたオーディオ構成はテストされていない。DirectPlayVoiceTest8.CheckAudioSetup メソッドを呼び出すこと。
DVERR_INCOMPATIBLEVERSION
クライアントは、ホストと互換性がない音声セッションに接続した。
DVERR_INITIALIZED
オブジェクトが既に初期化されているため、Initialize メソッドは失敗した。
DVERR_INVALIDPOINTER
指定されたポインタが無効である。
DVERR_NOTRANSPORT
指定されたオブジェクトは有効なトランスポートではない。
DVERR_NOCALLBACK
コールバック関数が指定されていないため、この処理は実行できない。
DVERR_TRANSPORTNOTINIT
指定されたトランスポートはまだ初期化されていない。
DVERR_TRANSPORTNOSESSION
指定されたトランスポートは有効だが、接続されていないかホストしていない。
DVERR_TRANSPORTNOPLAYER
指定されたトランスポートは接続され、ホストしているが、ローカル プレーヤーが存在しない。


DirectSetup

ここでは、Platform Software Development Kit (SDK) またはスタンドアローン DirectX SDK における Microsoft® DirectX® アプリケーション プログラミング インターフェイス (API) の Microsoft® DirectSetup® コンポーネントについて説明する。ここで説明する内容の大部分は、C++ 開発者向けのものである。Visual Basic® でのセットアップについては、「DirectX for Visual Basic アプリケーションのインストール」を参照すること。ここでは次のトピックに分けて説明する。

  • DirectSetup について
  • DirectSetup の要点
  • DirectX for Visual Basic アプリケーションのインストール
  • DirectSetup リファレンス
  • DirectSetup サンプル


DirectSetup について

Microsoft® DirectSetup は、Microsoft DirectX® のすべてのコンポーネントを一度の呼び出しでインストールするためのシンプルな API である。この API の意義は、単に便利というだけにとどまらない。DirectX は複雑な構成になっているため、インストールも複雑なタスクとなる。そのため、DirectX のインストールは手動で行うべきではない。

DirectSetup には、いくつかの API 関数と構造体が含まれる。そのほか、インストール プロセス用のユーザー インターフェイスをアプリケーション側でカスタマイズするためのプロトタイプとして、DirectXSetupCallbackFunction も 用意されている。DirectX SDK には、このコールバック関数の使用例を示すサンプル アプリケーションが収録されている。詳細については、「Dinstall サンプル」を参照すること。


DirectSetup の要点

ここでは、Microsoft® DirectSetup® コンポーネントの概要について説明する。説明する内容は以下のとおりである。

  • DirectSetup のセットアップの概要
  • セットアップ フォルダの準備
  • セットアップのカスタマイズ
  • セットアップ プログラムのテスト
  • AutoPlay の使用


DirectSetup のセットアップの概要

Microsoft® DirectX® をベースとするアプリケーションおよびゲームは、DirectXSetup 関数を使用して、既にインストールされている Microsoft Windows® システムに必要なシステム コンポーネントをインストールすることができる。この関数では、ディスプレイやオーディオ デバイスで適切に DirectX がサポートされるよう、ドライバのアップデートも行うことができる。DirectXSetup は、通常、アプリケーション ファイルのインストールに使用するプログラムから呼び出す。

注 : DirectXSetup 関数は、旧バージョンの DirectX システム コンポーネントを上書きする。たとえば、既に DirectX 7.0 のコンポーネントが存在するシステムに DirectX 8.0 をインストールすると、DirectX 7.0 のコンポーネントすべてが上書きされる。ただし、DirectX のコンポーネントはすべてコンポーネント オブジェクト モデル (COM) の下位互換性規則に準拠しているので、DirectX 7.0 用に記述したソフトウェアも引き続き正常に機能する。

DirectXSetup 関数は、DirectX コンポーネント、ディスプレイ ドライバ、オーディオ ドライバのアップグレードが必要なことを知らせることができる。また、これらのコンポーネントを、Windows オペレーティング システムに悪影響を与えることなしにアップグレードできるかどうかも判断できる。これがいわゆるセーフ アップグレードである。アップグレードの際は、コンピュータ上で動作しているアプリケーションだけでなく、オペレーティング システムに対する安全性も考慮する。また、Windows にとっては安全でも、一部のハードウェア依存アプリケーションに悪影響を与えてしまう場合もある。

デフォルトでは、DirectXSetup 関数は安全なアップグレードのみを実行する。デバイス ドライバのアップグレードによって Windows の動作に悪影響が及ぶ可能性がある場合、アップグレードは行われない。

セットアップ処理中、DirectSetup は置き換えるシステム コンポーネントとドライバのバックアップ コピーを作成する。これらのコピーは、問題が発生した場合に復元するためのものである。

ディスプレイ ドライバまたはオーディオ ドライバをアップグレードするとき、DirectXSetup 関数は、Microsoft 社が作成したデータベースを利用してアップグレード プロセスを管理する。このデータベースには、Microsoft 社、ハードウェアの製造元、またはハードウェアの販売元から提供されている既存のドライバについての情報が含まれている。また、Microsoft 社やその他のサイトで行われたテスト基づくそれぞれのドライバのアップグレード状況も記録されている。

DirectXSetup 関数を実行したら、戻り値をチェックする。戻り値が DSETUPERR_SUCCESS_RESTART の場合は、再起動するまで変更内容が有効にならないことをユーザーに知らせ、すぐに再起動するかどうか選択させる。この方法については、Dinstall サンプル アプリケーションの Dinstall.c の例を参照すること。


セットアップ フォルダの準備

DirectXSetup 関数は、インストールのルート ディレクトリを示すパラメータ lpszRootPath を取る。このパラメータを NULL にして、現在のディレクトリ (つまり、セットアップ プログラムが保存されているディレクトリ) をルート パスとすることもできる。

ルート ディレクトリには、dsetup.dll と dsetup32.dll を保存する必要がある。また、この中には「DirectX」 (大文字小文字の区別なし) という名前のフォルダを用意し、再配布可能なすべてのファイルおよびドライバを保存する。正しい構造のアプリケーション セットアップ ディスクは、Microsoft® DirectX SDK ディスクの Dxf\Redist\DirectX8 フォルダの内容すべてをセットアップ プログラムのルート パスにコピーすると作成できる。このフォルダは、SDK のインストール時に開発用のコンピュータにコピーされないので、オリジナル ディスクから別途コピーする必要がある。


セットアップのカスタマイズ

Microsoft® DirectSetup® では、Microsoft DirectX® セットアップ プロセスをカスタマイズするためのコールバック関数を定義することができる。このコールバック関数は、DirectSetup ドキュメントの中では DirectXSetupCallbackFunction と呼ばれているが、実際には任意の名前を割り当てることができる。

セットアップ プログラムでコールバック関数を使用しない場合、DirectXSetup 関数は、Microsoft Win32® MessageBox 関数を呼び出して、ダイアログ ボックス内にステータス情報やエラー情報を表示し、ユーザー入力の取得を行う。コールバック関数を使用する場合、このステータス ダイアログまたはメッセージ ボックスの作成に使用されるはずの情報は、代わりにコールバック関数に渡される。コールバック関数は、インストールまたはアップグレード可能な DirectX コンポーネントおよびデバイス ドライバごとに一度ずつ呼び出される。

コールバック関数は、以下の用途に使用できる。

  • カスタム インターフェイスの使用 - MessageBox や Microsoft Windows® の標準ダイアログ ボックス以外の方法で、セットアップ プログラムのメッセージを表示できる。コールバック関数を使うことで、DirectX コンポーネントのインストール用メッセージを、独自のインターフェイスに統合できる。
  • プログレス インジケータの更新
  • ステータス メッセージおよびエラー メッセージの表示制御 - 初心者向けのプログラムを開発する場合には、エラー メッセージを制御して、セットアップ プログラムにエラーの処理やアップグレードの選択を自動的に処理させたい場合がある。このようなセットアップ プログラムの開発には手間がかかるが、対象ユーザー層を考えると適切な措置といえる。

セットアップのカスタマイズにあたっては、次の各トピックを参考にすること。

  • DirectSetup コールバック関数の作成
  • コールバック関数の設定
  • コールバック関数でのアップグレード フラグの使い方
  • コールバック関数によるデフォルト動作の無効化


DirectSetup コールバック関数の作成

セットアップ プロセスをカスタマイズするには、まず次の宣言で示した DirectXSetupCallbackFunction プロトタイプに適合するコールバック関数を作成する。

DWORD WINAPI DirectXSetupCallbackFunction(
        DWORD dwReason,
        DWORD dwMsgType,
        LPSTR szMessage,
        LPSTR szName,
        void *pInfo);

この例 (Dinstall を修正したもの) では、関数名がプロトタイプと同じになっているが、これは変更可能である。パラメータ名は、dsetup.h ヘッダー ファイルで宣言されているプロトタイプと若干異なるが、以下の説明ではこれらの名前を使用する。

パラメータ

dwReason は、コールバック関数が呼び出された理由を示すパラメータである。有効値の一覧および各有効値の説明については、DirectXSetupCallbackFunction のリファレンスを参照すること。

dwMsgType パラメータは、Microsoft® DirectSetup® がデフォルトで MessageBox に渡すフラグ (表示するボタンやアイコンを制御するフラグなど) と同等のフラグを受け取る。中でも、ボタン フラグは、必要な戻り値の指定に使用できる。この値が 0 の場合、イベントはユーザー入力を要求しないため、DirectSetup は通常ステータス メッセージを表示する。

szMessage パラメータは、コールバック関数を使用しない場合に DirectSetup がステータス ダイアログ ボックスまたは MessageBox に渡すものと同じテキストを受け取る。

ドライバがアップグレード対象の場合、szName パラメータにドライバ名が渡され、pInfo はアップグレードの処理方法 (既存のドライバの使用を推奨する、アップグレードを推奨するなど) に関する情報を示す。詳細については、「コールバック関数でのアップグレード フラグの使い方」を参照すること。

コールバック関数が各パラメータをどのように解釈するかについては、開発者の裁量で決定する。通常は、表示するメッセージ (dwReason に基づく) とユーザーに選択肢を提示するタイミングを選択し、それに応じてインターフェイスを変更する。

戻り値

コールバック関数からの戻り値は、次の規則に従う必要がある。

  • dwMsgType が 0 の場合、戻り値は IDOK でなければならない。この場合、ユーザーに対する選択肢はない。(入力が必要ない場合でも、アプリケーションはステータス メッセージを表示してかまわない。)
  • dwMsgType が 0 以外の場合の戻り値は、MessageBox を使用した場合にユーザーが同様の選択をしたときに返される値と同じ値でなければならない。

dwMsgType が 0 以外の場合の適切な戻り値を確認するには、通常ならどのようなボタンがメッセージ ボックスに表示されるか実際にテストしてみる。次の例 (Dinstall の GetReply 関数より) は、このテスト方法を示したものである。

/* グローバル g_wReply は、ユーザーが選択したカスタム
ダイアログ ボタンを示す。 */

switch (dwMsgType & 0x0000000F)
{
   / * 通常、[OK] ボタンと [キャンセル] ボタンが配置される。
       IDBUT1 は [OK] ボタンに対応する。ユーザーが [OK] ボタンをクリックしなかった場合は、
       [キャンセル] ボタンがクリックされたと判定される。*/
    case MB_OKCANCEL:
        wDefaultButton = (g_wReply == IDBUT1) ? IDOK : IDCANCEL;
        break;

    / * 上記以外のボタンの組み合わせの場合は、以下のようになる。*/
    case MB_OK:
        wDefaultButton = IDOK;
        break;
    case MB_RETRYCANCEL:
        wDefaultButton = (g_wReply == IDBUT1) ? IDRETRY : IDCANCEL;
        break;
    case MB_ABORTRETRYIGNORE:
        if (g_wReply == IDBUT1)
            wDefaultButton = IDABORT;
        else if (g_wReply == IDBUT2)
            wDefaultButton = IDRETRY;
        else
            wDefaultButton = IDIGNORE;
        break;
    case MB_YESNOCANCEL:
        if (g_wReply == IDBUT1)
            wDefaultButton = IDYES;
        else if (g_wReply == IDBUT2)
            wDefaultButton = IDNO;
        else
            wDefaultButton = IDCANCEL;
        break;
    case MB_YESNO:
        wDefaultButton = (g_wReply == IDBUT1) ? IDYES : IDNO;
        break;
    default:
        wDefaultButton = IDOK;
}

このルーチンは、カスタム インターフェイスからのボタン クリックを、コールバック関数なしの場合に DirectSetup が作成する標準ダイアログ ボックス内の対応するボックス識別子に平行移動する。wDefaultButton 変数は、対応する標準ダイアログ ボックス ボタンの識別子に設定される。コールバック関数から返されるのは、この値である。

dwMsgType が 0 以外の値の場合でも、必ずしもユーザーに選択肢を与える必要はない。たとえば、DirectSetup が通常ユーザーに確認を求めるような場合でも、自動的にドライバをアップグレードすることも可能である。サンプルの Dinstall は、問題のある場合のみメッセージを表示するようユーザーが選択している場合で、しかもドライバをアップグレードしても安全であると考えられるときに、次のように自動アップグレードを行うようになっている。

case DSETUP_CB_UPGRADE_SAFE:
    switch (dwMsgType & 0x0000000F)
    {
        case MB_YESNO:
        case MB_YESNOCANCEL:
            return IDYES;
        case MB_OKCANCEL:
        case MB_OK:
        default:
            return IDOK;
    }
    break;

コールバック関数は、ユーザーにアップグレードを続行するかどうか確認するダイアログ ボックスで肯定を表すボタンに応じて、IDYES または IDOK を返す。


コールバック関数の設定

コールバック関数を使用する場合は、DirectXSetup を呼び出す前にシステムに知らせておく必要がある。これには、コールバックへのポインタをパラメータとして渡して DirectXSetupSetCallback 関数を呼び出す。次の例を参照すること。

DirectXSetupSetCallback(
        (DSETUP_CALLBACK) DirectXSetupCallbackFunction);


コールバック関数でのアップグレード フラグの使い方

アプリケーションで定義されたコールバック関数 DirectXSetupCallbackFunction が DirectXSetup 関数で呼び出されると、コールバック関数に呼び出し理由を示すパラメータが渡される。理由が DSETUP_CB_MSG_CHECK_DRIVER_UPGRADE の場合、pInfo パラメータは、DirextXSetup 関数が推奨する Microsoft® DirectX® コンポーネントおよびドライバのアップグレード方法をまとめたフラグを保持する DSETUP_CB_UPGRADEINFO 構造体を示す。これらのフラグを格納する構造体メンバは、UpgradeFlags と呼ばれる。

UpgradeFlags には次のようなカテゴリがある。

プライマリ アップグレード フラグ
これらのフラグは互いに排他的である。構造体メンバ UpgradeFlags には常にいずれか 1 つのフラグが存在する。フラグを抽出するには、DSETUP_CB_UPGRADE_TYPE_MASK とのビットごとの AND 処理をとる。

DSETUP_CB_UPGRADE_FORCE

DSETUP_CB_UPGRADE_KEEP

DSETUP_CB_UPGRADE_SAFE

DSETUP_CB_UPGRADE_UNKNOWN

セカンダリ アップグレード フラグ
これらのフラグの 1 つまたは両方を指定することができる。

DSETUP_CB_UPGRADE_CANTBACKUP

DSETUP_CB_UPGRADE_HASWARNINGS

デバイス アクティブ フラグ
ドライバをアップグレード中のデバイスがアクティブな場合に存在するフラグ。ほかのフラグと組み合わせて使用できる。

DSETUP_CB_UPGRADE_DEVICE_ACTIVE

デバイス クラス フラグ
これらのフラグは互いに排他的である。どちらかのフラグが必ず存在する。

DSETUP_CB_UPGRADE_DISPLAY

DSETUP_CB_UPGRADE_MEDIA

つまり、Reason パラメータの値が DSETUP_CB_MSG_CHECK_DRIVER_UPGRADE であれば、pInfo で指定される構造体メンバ UpgradeFlags には、常に 1 つの一次アップグレード フラグ、0 個以上の二次アップグレード フラグ、0 個または 1 つのデバイス アクティブ フラグ、および 1 つのデバイス クラス フラグが含まれる。

UpgradeFlags のメンバに DSETUP_CB_UPGRADE_KEEP が設定されている場合は、Windows® が正常に機能しなくなる恐れがあるため、DirectX コンポーネントやデバイス ドライバをアップグレードすることはできない。DirectXSetup 関数によるコンポーネントまたはドライバのアップグレードは行われない。

UpgradeFlags に DSETUP_CB_UPGRADE_FORCE という値がある場合は、Windows を正常に機能させるため、コンポーネントまたはドライバのアップグレードが必要である。このため、DirectXSetup 関数は、ドライバまたはコンポーネントのアップグレードを行う。ただし、アップグレードによって、システム上の一部のプログラムに悪影響が及ぶ可能性がある。DirectXSetup 関数がこの状態を検出すると、UpgradeFlags のメンバは (DSETUP_CB_UPGRADE_FORCE | DSETUP_CB_UPGRADE_HAS_WARNINGS) に設定される。この場合、DirectXSetup 関数は、アップグレードを実行する一方で、ユーザーに警告を発する。

コンポーネントおよびドライバをインストールしても Windows の動作に悪影響が及ばない場合、そのコンポーネントやドライバは安全にアップグレードできると見なされる。この場合、UpgradeFlags のメンバには DSETUP_CB_UPGRADE_SAFE が設定される。ただし、Windows に対しては安全であっても、システムにインストールされているプログラムに問題が発生する可能性はある。DirectXSetup 関数がこの状態を検出すると、UpgradeFlags のメンバには、値 (DSETUP_CB_UPGRADE_SAFE | DSETUP_CB_UPGRADE_HAS_WARNINGS) が格納される。この場合、DirectXSetup 関数のデフォルト動作では、アップグレードは実行されない。


コールバック関数によるデフォルト動作の無効化

アプリケーションで定義された関数 DirectXSetupCallbackFunction の戻り値を使って、DirectXSetup 関数のデフォルト動作の一部を無効化することができる。

たとえば、DirectXSetup のデフォルト動作では、pInfo パラメータが示す構造体内のアップグレード タイプが (DSETUP_CB_UPGRADE_SAFE | DSETUP_CB_UPGRADE_HAS_WARNINGS) に設定されているとコンポーネントはインストールされない。この場合、コールバック関数の MsgType パラメータは (MB_YESNO | MB_DEFBUTTON2) に設定される。コールバック関数を使用しない場合は、[No] がデフォルト ボタンになったダイアログ ボックスがユーザーに表示される。ユーザー入力を調べずにデフォルトを受け付ける場合、コールバック関数は IDNO を返す。デフォルトを無効にする場合は、IDYES を返す。デフォルトを無効にする場合、DirectXSetup 関数はユーザーに通知する。


セットアップ プログラムのテスト

作成したセットアップ プログラムの Microsoft® DirectSetup® コンポーネントをテストするには、DirectXSetup 関数に DSETUP_TESTINSTALL フラグを渡したバージョンをコンパイルする。そして、「セットアップ フォルダの準備」で説明したインストール ディレクトリをセットアップする。

セットアップ プログラムを実行すると、DirectSetup は、実際にはコンポーネントをインストールせずに、Microsoft DirectX® インストール時の模擬動作を行う。コールバック関数を設定している場合は、コールバック関数の動作も調べられる。


AutoPlay の使用

AutoPlay 対応の CD タイトルを作成するには、Microsoft® DirectX® SDK CD のルート ディレクトリ中の Autorun.inf ファイルを、アプリケーション ディレクトリのルートにコピーする。Autorun.inf は、以下の情報を格納するテキスト ファイルである。

[autorun]
OPEN=SETUP.EXE

アプリケーションのセットアップ プログラム名が Setup.exe の場合、このファイルを変更する必要はない。それ以外の名前が付いている場合は、実際のセットアップ プログラム名に合わせてこのファイルを編集しなければならない。


DirectX for Visual Basic アプリケーションのインストール

モジュール内で関数に参照を宣言すると、Microsoft Visual Basic アプリケーションで Microsoft® DirectSetup® 関数を使用できるが、推奨方法はアプリケーション ウィザードの使用である。CD-ROM でアプリケーションを配布するには、以下の操作を実行する。

Visual Basic アプリケーションの配布

  1. アプリケーション ウィザードを起動する。
  2. 依存リストから DxVBLib.dll を削除する。
  3. Microsoft Direct® SDK CD の Redist フォルダ (リテール用 \Dxf\Redist\Directx7、デバッグ用 \Dxf\Debug) のすべてのファイルを追加する。
  4. [Finish] ボタンをクリックし、アプリケーション ウィザードを終了する。
  5. DirectX SDK CD の support フォルダにある Setup1.exe を (アプリケーション ウィザードで作成された) Setup1.exe に上書きする。
  6. Visual Basic 5.0 を使用している場合は、圧縮ユーティリティを使って Setup1.exe を Setup1.ex_ に圧縮する。Visual Basic 6.0 で開発している場合は、アプリケーション ウィザードで作成されたバッチ ファイルを実行する。

これで、CD でファイルを配布する準備が整う。


DirectSetup リファレンス

ここでは、Microsoft® DirectSetup® の API 要素のリファレンス情報を記述する。リファレンス情報は以下のカテゴリに分類される。

  • 関数
  • 構造体
  • 戻り値

このリファレンスは主に、C++ でプログラミングを行うときに使用する。Microsoft® DirectX® for Microsoft Visual Basic® のセットアップ情報については、「DirectX for Visual Basic アプリケーションのインストール」を参照すること。


関数

ここでは、Microsoft® DirectSetup® で使用する以下のグローバル関数について説明する。

  • DirectXRegisterApplication
  • DirectXSetup
  • DirectXSetupCallbackFunction
  • DirectXSetupGetVersion
  • DirectXSetupSetCallback
  • DirectXUnRegisterApplication


DirectXRegisterApplication

アプリケーションを DirectPlayLobby 対応アプリケーションとして登録する。

int WINAPI DirectXRegisterApplication(
  HWND hWnd,
  LPDIRECTXREGISTERAPP lpDXRegApp
);

パラメータ

hWnd
親ウィンドウのハンドル。このパラメータが NULL の場合は、デスクトップが親ウィンドウとなる。
lpDXRegApp
DirectPlayLobby で正しくアプリケーションを動作させるために必要なレジストリ エントリを含む DIRECTXREGISTERAPP 構造体のアドレス。

戻り値

成功した場合は、TRUE を返す。

失敗した場合は、FALSE を返す。GetLastError 関数を使用すると、拡張エラー情報を取得できる。

注意

DirectXRegisterApplication 関数では、Dsetup.dll と Dsetup32.dll の両方が必要となる。これらのファイルはシステムにインストールされていないが、SDK に含まれている。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : dsetup.h で宣言。
インポート ライブラリ : dsetup.lib を使用。

参照

DirectXUnRegisterApplication


DirectXSetup

1 つまたは複数の Microsoft® DirectX® コンポーネントをインストールする。

int WINAPI DirectXSetup(
  HWND  hWnd,
  LPSTR lpszRootPath,
  DWORD dwFlags
);

パラメータ

hWnd
セットアップ ダイアログ ボックスの親ウィンドウのハンドル。
lpszRootPath
DirectX コンポーネント ファイルのルート パスを含む文字列のアドレス。この文字列には、ファイル Dsetup.dll および Dsetup32.dll と、再配布可能ファイルを格納した「DirectX」 (大文字小文字の区別なし) ディレクトリのあるディレクトリへのフル パスを指定しなければならない。この値が NULL の場合は、現在の作業ディレクトリが使用される。
dwFlags
インストール対象となる DirectX コンポーネントを示す 1 つまたは複数のフラグ。推奨は、フル インストール (DSETUP_DIRECTX)。
DSETUP_D3D | 使用しない。このフラグを使用する DirectX プログラムは、DirectX コンポーネントをすべてインストールする。
DSETUP_DDRAW | 使用しない。このフラグを使用する DirectX プログラムは、DirectX コンポーネントをすべてインストールする。
DSETUP_DDRAWDRV | DirectX 8.0 では使用しない。
DSETUP_DINPUT | 使用しない。このフラグを使用する DirectX プログラムは、DirectX コンポーネントをすべてインストールする。
DSETUP_DIRECTX | DirectX と互換性のあるディスプレイ ドライバおよびオーディオ ドライバに加え、DirectX ランタイム コンポーネントをインストールする。
DSETUP_DIRECTXSETUP | 使用しない。このフラグを使用する DirectX プログラムは、DirectX コンポーネントをすべてインストールする。
DSETUP_DPLAY | 使用しない。このフラグを使用する DirectX プログラムは、DirectX コンポーネントをすべてインストールする。
DSETUP_DPLAYSP | 使用しない。このフラグを使用する DirectX プログラムは、DirectX コンポーネントをすべてインストールする。
DSETUP_DSOUND | 使用しない。このフラグを使用する DirectX プログラムは、DirectX コンポーネントをすべてインストールする。
DSETUP_DSOUNDDRV | DirectX 8.0 では使用しない。
DSETUP_DXCORE | DirectX ランタイム コンポーネントをインストールする。DirectX と互換性のあるディスプレイ ドライバとオーディオ ドライバはインストールしない。
DSETUP_TESTINSTALL | インストール内容をテストする。新しいコンポーネントをインストールすることはない。
DSETUP_USEROLDERFLAG | -14 を返せる。これは、インストールされている DirectX のバージョンがインストールするバージョンよりも新しいことを意味する。

戻り値

この関数が成功した場合、以下の成功コードのうちの 1 つを返す。

DSETUPERR_SUCCESS | インストールが成功した。
DSETUPERR_SUCCESS_RESTART | インストールが成功したが、変更内容を有効にするためにシステムを再起動する必要がある。

失敗した場合は、エラー コードを返す。戻り値については、「戻り値」を参照すること。

注意

セットアップ プログラムで DirectXSetup 関数を使用する前に、システムに最低 15 MB の空きディスク領域があることを確認すること。これは適切なファイルをセット アップするために DirectX が必要とする最大領域である。ただし、システムに DirectX ファイルが既に存在する場合は必要ない。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : dsetup.h で宣言。
インポート ライブラリ : dsetup.lib を使用。


DirectXSetupCallbackFunction

オプションでセットアップ プログラムに設定するコールバック関数のプレースホルダ名である。設定されたコールバック関数は、セットアップ プロセスの各ステップごとに一度ずつ呼び出される。

DWORD DirectXSetupCallbackFunction(
  DWORD  Reason,
  DWORD  MsgType,
  char  *szMessage,
  char  *szName,
  void  *pInfo
);

パラメータ

Reason
コールバックの理由。次のいずれかの値を取る。
DSETUP_CB_MSG_BEGIN_INSTALL
DirectXSetup が Microsoft® DirectX® コンポーネントとデバイス ドライバのインストールを始めようとしている。
DSETUP_CB_MSG_BEGIN_INSTALL_DRIVERS
DirectXSetup がデバイス ドライバのインストールを始めようとしている。
DSETUP_CB_MSG_BEGIN_INSTALL_RUNTIME
DirectXSetup が DirectX コンポーネントのインストールを始めようとしている。
DSETUP_CB_MSG_BEGIN_RESTORE_DRIVERS
DirectXSetup が以前のドライバの復元を始めようとしている。
DSETUP_CB_MSG_CANTINSTALL_BETA
Microsoft Windows® 95 オペレーティング システムのベータ バージョンが検出された。DirectX コンポーネントまたはデバイス ドライバをインストールできない。
DSETUP_CB_MSG_CANTINSTALL_NOTWIN32
Windows 32 ビット以外のオペレーティング システムが検出された。DirectX は Windows3.x と互換性はない。
DSETUP_CB_MSG_CANTINSTALL_NT
DirectX コンポーネントまたはデバイス ドライバは、バージョン 4.0 より前の Microsoft Windows NT® オペレーティング システムにはインストールできない。
DSETUP_CB_MSG_CANTINSTALL_UNKNOWNOS
オペレーティング システムが既知のものではない。DirectX コンポーネントまたはデバイス ドライバをインストールできない。
DSETUP_CB_MSG_CANTINSTALL_WRONGLANGUAGE
DirectX コンポーネントまたはデバイス ドライバを、Windows で使用されている言語にローカライズすることができない。
DSETUP_CB_MSG_CANTINSTALL_WRONGPLATFORM
DirectX コンポーネントまたはデバイス ドライバが別の種類のコンピュータ用のものである。
DSETUP_CB_MSG_CHECK_DRIVER_UPGRADE
ドライバのアップグレードが必要と考えられる。ユーザー側の確認を推奨する。
DSETUP_CB_MSG_FILECOPYERROR
DirectX コンポーネントまたはデバイス ドライバ ファイルのセットアップがコピー プロセス中に失敗した。
DSETUP_CB_MSG_INTERNAL_ERROR
内部エラーが発生した。DirectX コンポーネントまたはデバイス ドライバのセットアップが失敗した。
DSETUP_CB_MSG_NOMESSAGE
表示するメッセージがない。コールバック関数は戻らなければならない。
DSETUP_CB_MSG_NOTPREINSTALLEDONNT
使用している Microsoft Windows NT または Microsoft Windows 2000 のバージョンに DirectX コンポーネントまたはデバイス ドライバがインストールできない。
DSETUP_CB_MSG_OUTOFDISKSPACE
DirectX コンポーネントのセットアップがディスク領域不足のために失敗した。
DSETUP_CB_MSG_PREINSTALL_NT
使用している Windows NT または Windows 2000 のバージョンに既に DirectX がインストールされている。
DSETUP_CB_MSG_SETUP_INIT_FAILED
DirectX コンポーネントまたはデバイス ドライバのセットアップが失敗した。
MsgType
メッセージ ボックスの表示を制御するフラグ。これらのフラグは、MessageBox 関数に渡すことができる。MsgType が 0 のときは例外で、セットアップ プログラムはステータス情報を表示することはできるが、ユーザーからの入力待ちをしてはいけない。
szMessage
エラー メッセージまたはステータス情報を含むローカライズ文字列へのポインタ。これらの文字列は、MessageBox 関数で作成されるダイアログ ボックスに表示できる。
szName
Reason パラメータが DSETUP_CB_MSG_CHECK_DRIVER_UPGRADE でない限り NULL である。この場合、szName にはアップグレードするドライバの名前へのポインタが入る。
pInfo
アップグレード情報を含む構造体のアドレスへのポインタ。Reason が DSETUP_CB_MSG_CHECK_DRIVER_UPGRADE の場合は、セットアップ プログラムがドライバのアップグレード中で、ユーザーにアップグレードを行うべきかどうかを問い合わせている。この場合、pInfo は、アップグレードに関する情報を格納する DSETUP_CB_UPGRADEINFO 構造体を示す。

戻り値

1 つの例外を除いて、戻り値は MessageBox 関数から返される戻り値と同じでなければならない。この関数が 0 を返した場合、DirectXSetup 関数は デフォルトの動作で DirectX コンポーネントまたはドライバのアップグレードを実行する。

注意

DirectXSetupCallbackFunction の名前はセットアップ プログラムから与えられる。DirectXSetupSetCallback 関数は、DirectSetup にコールバック関数のアドレスを渡す際に使用される。

MsgType が 0 の場合、セットアップ プログラムでステータス情報を表示できるが、ユーザーからの入力待ちをしてはいけない。この場合、関数は IDOK を返す。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : dsetup.h で宣言。
インポート ライブラリ : ユーザー定義。

参照

MessageBox、DirectXSetupSetCallback、セットアップのカスタマイズ


DirectXSetupGetVersion

現在インストールされている Microsoft® DirectX® コンポーネントのバージョン番号を取得する。

INT WINAPI DirectXSetupGetVersion(
  DWORD  *pdwVersion,
  DWORD  *pdwRevision
);

パラメータ

pdwVersion
バージョン番号を受け取る変数のアドレスへのポインタ。バージョン番号が不要の場合は NULL でも可。
pdwRevision
リビジョン番号を受け取る変数のアドレスへのポインタ。リビジョン番号が不要の場合は NULL でも可。

戻り値

成功した場合は、0 以外の値を返す。

失敗した場合は、0 を返す。

注意

DirectXSetupGetVersion 関数は、DirectXSetup 関数を呼び出す前後にバージョン番号とリビジョン番号を取得するために使用する。DirectXSetup の呼び出し前にこの関数を呼び出した場合は、現在インストールされている DirectX コンポーネントのバージョン番号とリビジョン番号が与えられる。DirectXSetup の呼び出し後で、しかもコンピュータを再起動する前にこの関数を呼び出した場合は、コンピュータを再起動した後に有効になる DirectX コンポーネントのバージョン番号とリビジョン番号が与えられる。

pdwVersion パラメータに格納されるバージョン番号は、メジャー バージョン番号とマイナー バージョン番号から成る。関数から返されたメジャー バージョン番号は、DWORD の上位 16 ビットに格納される。関数から返されたマイナー バージョン番号は、DWORD の下位 16 ビットに格納される。バージョン番号と実際のバージョンは次のように対応している。

DirectX のバージョン | pdwVersion によってポイントされる値
DirectX 1 | 0x00000000
DirectX 2 | 0x00000000
DirectX 3 | 0x00000000
DirectX 5.0 | 0x00040005
DirectX 6.0 | 0x00040006
DirectX 7.0 | 0x00040007
DirectX 8.0 | 0x00040008

DirectX のバージョン 4 は存在しない。

pdwRevision パラメータに格納されるバージョン番号は、リリース番号とビルド番号から成る。関数から返されたリリース番号は、DWORD の上位 16 ビットに格納される。関数から返されたビルド番号は、DWORD の下位 16 ビットに格納される。

次のサンプル コードは、DirectXSetupGetVersion から返された情報を取り出して使用する方法を示したものである。

DWORD dwVersion;
DWORD dwRevision;
if (DirectXSetupGetVersion(&dwVersion, &dwRevision))
{
    printf("DirectX version is %d.%d.%d.%d\n",
           HIWORD(dwVersion), LOWORD(dwVersion),
           HIWORD(dwRevision), LOWORD(dwRevision));
}

バージョン番号とリビジョン番号は、64 ビット データに結合して比較することができる。このとき、バージョン番号は上位 32 ビットに、リビジョン番号は下位 32 ビットにそれぞれ格納される。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : dsetup.h で宣言。
インポート ライブラリ : dsetup.lib を使用。

参照

DirectXSetup


DirectXSetupSetCallback

DirectXSetup から周期的に呼び出されるコールバック関数にポインタをセットする。コールバック関数は、セットアップの進行状況の通知と、アプリケーションのセットアップ プログラム用のカスタム ユーザー インターフェイスの実装に使用することができる。詳細については、DirectXSetupCallbackFunction を参照すること。セットアップ プログラムがコールバック関数を与えない場合、DirectXSetupSetCallback は呼び出されない。

INT WINAPI DirectXSetupSetCallback(
  DSETUP_CALLBACK  Callback
);

パラメータ

Callback
コールバック関数のアドレス。

戻り値

現状では 0 を返す。

注意

コールバック関数を設定するには、DirectXSetup を呼び出す前に DirectXSetupSetCallback を呼び出さなければならない。

DirectXSetupSetCallback に渡されるコールバック関数の名前は、セットアップ プログラムによって与えられる。ただし、DirectXSetupCallbackFunction で与えられるプロトタイプに適合するものでなければならない。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : dsetup.h で宣言。
インポート ライブラリ : dsetup.lib を使用。

参照

DirectXSetupCallbackFunction、DirectXSetup


DirectXUnRegisterApplication

DirectPlayLobby 対応アプリケーションの登録を削除する。

int WINAPI DirectXUnRegisterApplication(
  HWND   hWnd,
  LPGUID lpGUID
);

パラメータ

hWnd
親ウィンドウのハンドル。デスクトップが親ウィンドウのときは、このパラメータに NULL を設定する。
lpGUID
削除対象となる Microsoft® DirectPlay アプリケーションの GUID のアドレス。

戻り値

成功した場合は、TRUE を返す。これは登録の削除に成功したことを示す。

失敗した場合は、FALSE を返す。

注意

DirectXUnRegisterApplication 関数では、Dsetup.dll と Dsetup32.dll の両方が必要となる。これら 2 つのファイルはシステムにインストールされていないが、SDK に含まれている。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : dsetup.h で宣言。
インポート ライブラリ : dsetup.lib を使用。

参照

DirectXRegisterApplication


構造体

ここでは、Microsoft® DirectSetup® で使用される以下の構造体について説明する。

  • DIRECTXREGISTERAPP
  • DSETUP_CB_UPGRADEINFO

注 : Microsoft DirectX® 構造体のメモリはすべて、使用前に 0 に初期化しなければならない。また、dwSize メンバを持つすべての構造体は、使用前にこのメンバを構造体のサイズ (バイト単位) に設定しなければならない。


DIRECTXREGISTERAPP

DirectPlayLobby 対応アプリケーションに必要なレジストリ エントリを格納する。

typedef struct _DIRECTXREGISTERAPP {
    DWORD  dwSize;
    DWORD  dwFlags;
    LPSTR  lpszApplicationName;
    LPGUID lpGUID;
    LPSTR  lpszFilename;
    LPSTR  lpszCommandLine;
    LPSTR  lpszPath;
    LPSTR  lpszCurrentDirectory;
} DIRECTXREGISTERAPP, *PDIRECTXREGISTERAPP, *LPDIRECTXREGISTERAPP;

メンバ

dwSize
構造体の大きさ。DIRECTXREGISTERAPP 構造体の大きさに初期化されなければならない。
dwFlags
予約ビット。
lpszApplicationName
アプリケーションの名称。
lpGUID
アプリケーションのグローバル ユニーク識別子 (GUID)。
lpszFilename
呼び出される実行ファイル名。
lpszCommandLine
実行ファイルのコマンドライン引数。
lpszPath
実行ファイルのパス。
lpszCurrentDirectory
カレント ディレクトリ。通常は lpszPath と同じ。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : dsetup.h で宣言。


DSETUP_CB_UPGRADEINFO

パラメータとしてアプリケーションで定義した DirectXSetupCallbackFunction へ渡される。この構造体には、Reason パラメータが DSETUP_CB_MSG_CHECK_DRIVER_UPGRADE のときだけ、有効な情報が格納される。コールバック関数は、この構造体を使用して、実行するアップグレードに関するステータス情報を取得することができる。

typedef struct _DSETUP_CB_UPGRADEINFO {
    DWORD UpgradeFlags;
} DSETUP_CB_UPGRADEINFO;

メンバ

UpgradeFlags
アップグレード ステータスは 1 つ以上のフラグで示される。次の各値が定義されている。
DSETUP_CB_UPGRADE_CANTBACKUP
古いシステム コンポーネントをバック アップできない。アップグレードは実行可能だが、アップグレード後のコンポーネントやドライバの復元はできない。
DSETUP_CB_UPGRADE_DEVICE_ACTIVE
デバイスは現在使用中である。
DSETUP_CB_UPGRADE_DEVICE_DISPLAY
アップグレード対象のデバイス ドライバは、ディスプレイ デバイス用のドライバである。
DSETUP_CB_UPGRADE_DEVICE_MEDIA
アップグレード対象のデバイス ドライバは、メディア デバイス用のドライバである。
DSETUP_CB_UPGRADE_FORCE
コンポーネントがアップグレードされなければ、Microsoft® Windows® が正常に機能しない恐れがある。アップグレードは実行される。
DSETUP_CB_UPGRADE_HASWARNINGS
Microsoft DirectSetup® でこのデバイスのドライバをアップグレードすることはできるが、システム上の 1 つ以上のプログラムに影響を与える恐れがある。影響を受けると見られるプログラムの名前は szMessage に格納される。アップグレードは推奨されない。
DSETUP_CB_UPGRADE_KEEP
このデバイス ドライバをアップグレードすると、システムに障害が発生する恐れがある。アップグレードは許可されない。
DSETUP_CB_UPGRADE_SAFE
DirectSetup はこのデバイス ドライバを安全にアップグレードできる。アップグレードが推奨される。安全なアップグレードとは、Windows の動作に悪影響を与えないことを示す。ハードウェアに依存する一部のプログラムについては、悪影響が及ぶ可能性がある。
DSETUP_CB_UPGRADE_UNKNOWN
このデバイスの既存のドライバが認識できない。この値の状況は頻繁に発生する。アップグレードすることにより、このデバイスの使用に悪影響を与える可能性がある。アップグレードを実行しないよう強く推奨する。

注意

UpgradeFlags からアップグレード タイプ (FORCE、KEEP、SAFE、または UNKNOWN) を取得するには、値 DSETUP_CB_UPGRADE_TYPE_MASK を使用する。

動作環境

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
ヘッダー : dsetup.h で宣言。

参照

DirectXSetupCallbackFunction


戻り値

DirectXSetup 関数は以下の値を返す。この関数では標準 COM エラーを返すこともできる。

DSETUPERR_SUCCESS
セットアップが成功した。再起動の必要はない。
DSETUPERR_SUCCESS_RESTART
セットアップが成功した。再起動する必要がある。
DSETUPERR_BADSOURCESIZE
ファイル サイズを検証できなかったか、誤りであった。
DSETUPERR_BADSOURCETIME
ファイルの日付およびタイムを検証できなかったか、誤りであった。
DSETUPERR_BADWINDOWSVERSION
システムで実行中の Microsoft Windows® は、Microsoft® DirectX® ではサポートされない。
DSETUPERR_CANTFINDDIR
セットアップ プログラムで作業ディレクトリが見つからなかった。
DSETUPERR_CANTFINDINF
必要な .inf ファイルが見つからなかった。
DSETUPERR_INTERNAL
内部エラーが発生した。
DSETUPERR_NEWERVERSION
DirectX の上位バージョンが既にインストールされている。上位バージョンが上書きされることはなく、以前のバージョン用に記述されたアプリケーションとも完全に互換性があるため、アプリケーションは安全にこのエラーを無視できる。
DSETUPERR_NOTADMIN
カレント ユーザーが管理者権限を持っていない。Windows 2000 システムでは、セットアップの際に管理者権限が必要な場合がある。
DSETUPERR_NOCOPY
ファイルのバージョンを検証できなかったか、誤りであった。
DSETUPERR_NOTPREINSTALLEDONNT
システムの Windows NT® または Windows 2000 のバージョンに、DirectX の最新バージョンが含まれていない。DirectX の古いバージョンが存在するか、DirectX のどのバージョンも存在しないか、どちらかの可能性がある。
DSETUPERR_OUTOFDISKSPACE
セットアップ プログラムによるインストール中にディスク領域が足りなくなった。
DSETUPERR_SOURCEFILENOTFOUND
必要なソース ファイルのうちのいずれかが見つからなかった。
DSETUPERR_UNKNOWNOS
サポートされていないバージョンのオペレーティング システムである。
DSETUPERR_UNSUPPORTEDPROCESSOR
サポートされていないプロセッサ タイプである。DirectX 8 では、Pentium または K6 互換プロセッサおよびこれら以降のプロセッサのみをサポートしている。
DSETUPERR_USERHITCANCEL
アプリケーションのインストールが完了する前に、[Cancel] ボタンが押された。


DirectSetup サンプル

Microsoft® DirectSetup® の使用方法および機能を説明するサンプルとして、次のプログラムが提供されている。

  • Dinstall サンプル (C/C++)
  • DXVBSetup サンプル (Microsoft Visual Basic)

DirectX サンプルには Microsoft Visual C++® のプロジェクト ワークスペース ファイルが含まれているが、各自の開発環境で正しくコンパイルできるようにほかの設定を確認する必要がある場合がある。詳細については、「DirectX のサンプルおよびその他の DirectX アプリケーションのコンパイル」を参照すること。


Dinstall サンプル

ここでは、C++ でのアプリケーション開発について説明する。Microsoft® Visual Basic® については、「DXVBSetup サンプル」を参照すること。


DXVBSetup サンプル

説明

DXVBSetup サンプルは、Microsoft® DirectSetup® を Microsoft Visual Basic® アプリケーションで使用する方法を示したものである。

パス

(SDK ルート)\Samples\Multimedia\VBSamples\Misc\DXSetup

ユーザーズ ガイド

セットアップ アプリケーション ディレクトリには、Dsetup.dll および Dsetup32.dll を含む Setup というサブフォルダがなければならない。また、この中には「DirectX」 (大文字小文字の区別なし) という名前のフォルダを用意し、再配布可能なすべてのファイルおよびドライバを保存する。正しい構造のアプリケーション セットアップ ディスクは、Microsoft DirectX® SDK ディスクの \Redist\DirectX8 フォルダの内容すべてをセットアップ プログラムのルート パスにコピーすると作成できる。このフォルダは、SDK のインストール時に開発用のコンピュータにコピーされないので、オリジナル ディスクから別途コピーする必要がある。


用語集

ここでは、Microsoft® DirectX® SDK のドキュメントで使用される技術用語を解説する。

A, B, C, D, E, F, G, H, I, J, K, L, M, N, O, P, Q, R, S, T, U, V, W, X, Y, Z


A

アルファ チャネル (alpha channel)
アルファ値によって定義される、画像の不透明度。不透明度を定義するアルファ値は、ピクセル単位にほかの色成分と共に与えられるか (ARGB などの場合)、独立したアルファ サーフェス内でピクセル単位に与えられるか、またはサーフェス全体に固定の値で与えられる。
アルファ色成分 (alpha color component)
32 ビット カラーの不透明度を決める部分。32 ビット カラーの場合、アルファ値は、ピクセル単位にほかの色成分と共に与えられる (ARGB など)。まれに、独立したアルファ サーフェス内にピクセル単位のアルファ値が格納されている画像のアルファ値を指して 買Aルファ成分� という場合もある。
アルファ定数 (alpha constant)
サーフェス全体に適用される不透明度 (アルファ値)。
アルファ エッジ ブレンド (alpha edge blend)
アルファ ブレンディング (およびアルファ チャネル情報) の用法の 1 つ。 ピクセルの適用範囲に基づいてエッジを混色することにより、エイリアシングを減少させる方法である。
アンビエント属性 (ambient property)
環境光属性、ライトからの角度に依存せず反射するマテリアル属性。 オブジェクトの向き、位置、表面特性などに関係なく、シーンのすべてを照らす光源およびマテリアル属性。シーンのすべての場所を同じ光源で照らすため、アンビエント光源に置かれたフレームの位置や向きは重要ではない。複数のアンビエント光源がシーン内で組み合わされる。
異方性フィルタリング (anisotropic filtering)
異方性の歪みを補正するミップマップ フィルタリング モードの 1 つ。
異方性 (anisotropy)
表面が表示面に対して角度を持って位置する 3D オブジェクトのイメージに生じる、目に見える歪み。異方性はテクスチャ空間へ逆マップされたスクリーン ピクセルの伸び (長さ÷幅) として計測できる。
配列オブジェクト (array object)
1 つの配列にまとめられたオブジェクト群。配列オブジェクトを使用すると、一連のオブジェクトすべてに何らかの処理を行う場合の操作が簡単になる。配列オブジェクトを扱うことができる COM インターフェイスには、GetElement と GetSize というメソッドが用意されている。この 2 つのメソッドはそれぞれ、配列要素へのポインタの取得、および配列サイズの取得を行う。
アタッチ (attach)
複数の DirectDrawSurface オブジェクトを接続して、Z バッファ付きの 3D ページ プリッピングをサポートする場合などに必要となる複合構造体にすること。アタッチは双方向的なものではない。 サーフェスをそのサーフェス自身にアタッチすることはできない。また、(システム メモリ内で) エミュレートされているサーフェスを、エミュレートによらないサーフェスにアタッチすることもできない。2 つのサーフェスをアタッチする場合、片方のサーフェスがテクスチャ マップでない限り、アタッチされるサーフェスどうしは同一サイズでなければならない。
アタッチ状態 (attached)
システムに物理的に接続されている状態。デバイスは、インストールされていても、アタッチ状態にはない場合もある。
アタック (attack)
マグニチュードが基本レベル (維持期間レベル) に達してフォース フィードバック エフェクトが始まるときの初期期間。


B

バック バッファ (back buffer)
画面に表示されていないサーフェス。 アプリケーションは、フロント バッファのイメージが画面に表示されている間に、ビットマップやその他のイメージをバック バッファに描き込むことができる。
後方クリップ面 (back clipping plane)
視錐台の奥行きの限界。 この向こう側にあるオブジェクトはレンダリングされない。「前方クリップ面」を参照すること。
バンク セレクト (bank select)
MIDI のコントロール チェンジ。 異なるグループ (バンク) からの音色選択を可能にする。 各バンクの識別には、2 バイト コードが使用される。
ビルボード (billboard)
1 つの面がビューアに向くような方向で 3D シーンへ挿入されたプリミティブ。テクスチャ (通常は、アニメーションされたスプライト) をビルボードに適用すると、3D オブジェクトがシーン上に現れる。
ビルボーディング (billboarding)
シーン上の 3D オブジェクトの外観をシミュレートする 2D 技法。アプリケーションは、プリミティブ (通常は矩形) を 1 つの面がビューアに向くような方向でシーンに挿入し、1 つのテクスチャまたは一連のテクスチャをそこへ適用する。適用されたテクスチャは、アニメーションされた 3D オブジェクトに見える。
ブレンディング係数 (blend factor)
テクスチャ ブレンディングにおいて、各色成分がどのように混色されるかを示す係数。
ブレンディング モード (blend mode)
テクスチャが適用先のサーフェスの色とどのように混色されるかを決定するアルゴリズム。
ブレンディング ステージ (blending stage)
テクスチャ カスケードの 1 ステップ。ブレンディング ステージは、1 つのテクスチャと、複数のテクスチャを混色する際に使用される一連のテクスチャ ブレンディング処理から成る。
ブリット (blit)
ビットのブロック転送。
境界チェック (bounds checking)
画面上のイメージが画面の境界内に表示されているかどうかをチェックする処理。
バンプ マッピング (bump mapping)
3D シーンでサーフェスが凸凹した外観をシミュレートする技法。深さの変化がテクスチャ内に格納され、標準のテクスチャ ブレンディング技術を使用してプリミティブに適用される。


C

カメラ (camera)
表示位置と方向を定義するため、ビューポートが用いる Direct3DRMFrame オブジェクト。ビューポートは、カメラ フレームの正の z 軸上にある可視オブジェクトだけを、y 軸上の正方向にレンダリングする。
カメラ空間 (camera space)
視点が原点に位置し、そこから z 軸の正の方向を見ている基準フレーム。オブジェクトの座標は、ビュー トランスフォームによりワールド空間からカメラ空間へとトランスフォームされる。
クライアント/サーバー セッション (client/server session)
サーバーだけがセッションの完全な状態を格納する Microsoft® DirectPlay® セッション。 各クライアントはセッション状態のサブセットだけを保持する。各クライアントは、サーバーからそのコンピュータに関する情報だけを受け取る。あるコンピュータで何かを変更した場合は、サーバーにその変更を伝える。その後、サーバーは変更についてどのクライアントに通知すべきかを判断する。「ピアツーピア セッション」を参照すること。
クリップ リスト (clip list)
サーフェスの可視領域を示す矩形のリスト。既に DirectDrawClipper オブジェクトにウィンドウ ハンドルが結び付けられている場合は、クリップ リストを設定することはできない。
クリッパー (clipper)
DirectDrawClipper オブジェクトのこと。
CODEC
圧縮伸張システム (COmpressor and DECompressor) を表す略語。
衝突検出 (collision detection)
2 つのイメージに画面上の同じ位置を共有するピクセルがないか判断する処理。「ヒット検出」を参照すること。
カラー キー (color key)
透明エフェクトや半透明エフェクトに使用される色を示す値。たとえば、ハードウェアのブリット機能を使用した場合、矩形領域内のカラー キーとして設定された値を持つピクセル以外のすべてのピクセルがブリットされる。 これは、矩形でないスプライトをサーフェス上に作成する。
色空間 (color space)
3 つ以上の座標値で色を表すモデルのこと。色空間モデルは、色の各成分を、3 次元以上のデカルト座標系にマッピングする。色空間は、色のコード化と可視化に複数の手法を用いる場合もある。最も一般的な色空間モデルは、RGB と YUV の 2 つである。
色空間の変換 (color-space conversion)
異なる色空間間で色を変換すること。通常は、ビデオ ソースの YUV カラーから表示用の RGB 色への変換のことをいう。
カラー テーブル (color table)
n 色のカラー値の配列 (通常は RGB 三原色)。
複合サーフェス (complex surface)
ルート サーフェスにアタッチされている複数の DirectDrawSurface オブジェクトをまとめて指す用語。複合サーフェス構造体は、ルートを破棄することによってしか破棄できない。
制御セグメント (control segment)
再生の一定局面を制御するミュージカル セグメント。通常はプライマリ セグメントであるが、制御セグメントとしてセカンダリ セグメントを指定することができる。
カリング (culling)
レンダリング処理で 3D プリミティブの背面等を省くこと。
カーブ (curve)
Microsoft® DirectMusic® で、開始と終了の値を持つ一連のイベント。ボリュームのフェードなど。


D

暗色光 (dark light)
シーンからライトを除去する光源。 暗色光は、ライトの色に負の値を指定することにより作成できる。
DCI
Display Control Interface (ディスプレイ コントロール インターフェイス) の略。DCI は、Intel および Microsoft® により定義されたインターフェイスで、ビデオ メモリに直接アクセスすることによって、より高いグラフィックス パフォーマンスを提供する。
デッドバンド (deadband)
フォース フィードバック軸のオフセットの周囲にある、条件が作用しない領域。
デッド ゾーン (dead zone)
軸の物理的な動作範囲内で、軸が中心に位置していると見なされる領域。
デカール (decal)
ビジュアル オブジェクトとして直接レンダリングされるテクスチャ。ビューポートに位置を合わせた矩形にレンダリングされる。
転送先カラー キー (destination color key)
ブリットの場合は置き換えられる色、オーバーレイの場合は転送先のサーフェス上で覆い隠される色のこと。
デバイス ウィンドウ (device window)
Microsoft® DirectDraw® が表示用に使用するアプリケーション ウィンドウ。アプリケーションは、与えられたコンピュータにアタッチされている各表示デバイスに 1 つずつデバイス ウィンドウを持つことができる。「フォーカス ウィンドウ」を参照すること。
ディレクショナル (directional)
フレームにアタッチされるが、すべてのオブジェクトを同じ輝度で照らす光源の記述。 あたかも光源がオブジェクトから無限の距離に位置するかのようなエフェクトを与える。ディレクショナル ライトは、向きは持つが位置を持たず、一般に、太陽のような遠く離れた光源をシミュレートするために用いられる。
DirectPlay アドレス (DirectPlay address)
Microsoft® DirectPlay® がロビー サーバー、アプリケーション、DirectPlay、およびサービス プロバイダの間でアドレス情報を渡すために使用するデータ形式。DirectPlay アドレスは、グローバル ユニーク識別子 (GUID) でタグ付けされた一連の可変長のデータ チャンクである。 GUID は、DirectPlay に必要なアドレス情報をすべて提供する。アドレス情報の例として、サーバーのネットワーク アドレス、プレーヤーのネットワーク アドレス、プレーヤーの電子メール名、セッションのネットワーク アドレスなどが挙げられる。
DLS
DownLoadable Sounds (ダウンロード可能なサウンド) の略。ソフトウェアに格納されているデジタル サンプルからウェーブ サウンドを合成する機能についての標準。MIDI Manufacturers Association から DLS レベル 1 およびレベル 2 の標準が発表されている。
DMO
Microsoft® DirectX® Media Object (Microsoft® DirectX® メディア オブジェクト) の略。クライアントによって割り当てられたバッファからのマルチメディア データ ストリームを処理する COM オブジェクト。


E

エミッション属性 (emissive property)
自己発色属性、マテリアル (素材) のライトに依存しない色属性を示すマテリアル属性、発光または発色。マテリアルの反射および発光を決定する属性は 4 つあるが、エミッション属性はそのうちの 1 つである。「アンビエント属性」、「ディフューズ属性」、および「スペキュラ属性」を参照すること。
エミッション設定 (emissive setting)
「エミッション属性」を参照すること。
有効フレーム (enable frame)
光源を適用することができるフレーム。
エンベロープ (envelope)
フォース フィードバックで、初期 (アタック) と終期 (フェード) でのマグニチュードを変更することにより、エフェクトの形状を定義する一連の値。

オーディオでは、サウンドの振幅またはピッチの形状を定義する一連の値。DLS レベル 1 では、アタック、ディケイ、サステイン、リリース (ADSR) の 4 セグメント エンベロープが定義されている。DLS レベル 2 では、ディレイ、アタック、ホールド、ディケイ、サステイン、リリース (DAHDSR) の 6 セグメントが定義されている。

偶数フィールド (even field)
ビデオ フレームを構成する奇数/偶数のフィールド セットの 2 つ目のフィールド。フィールド 2 とも呼ばれる。
実行バッファ (execute buffer)
3D シーンを記述する、すべての情報が格納されていて独立した情報パケット。実行バッファには、頂点のリストが格納され、それに続いて命令ストリームが格納される。命令ストリームは、オペレーション コード (オペコード) と、そのオペコードによる処理の対象となるデータから成る。


F

面 (face)
メッシュ内の単一のポリゴン。
フェード (fade)
フォース フィードバック エフェクトの中央部分 (維持期間) からフォース フィードバック エフェクトが終わるまでの期間。
フォールオフ (falloff)
スポットライトの内側の円錐面と外側の円錐面との間の光の減衰。
フィールド (field)
ビデオ ストリーム内の単一のビデオ フレームの半分に相当するデータ。各フィールドには、1 つおきの走査線のデータが格納される。フィールドの送受信は、奇数フィールド、偶数フィールドの順で行われる。
フィールド極性 (field polarity)
フィールドが偶数フィールドと奇数フィールドのどちらであるかを表す特性。奇数フィールドでは、走査線中に VREF の立ち下がりエッジは発生しない。偶数フィールドでは、走査線中に VREF の立ち下がりエッジが発生する。
フリマリング (flimmering)
z 値の分離が不完全なため、転写時に 3D プリミティブ上に発生する表示のちらつき。背面のテクスチャの一部のピクセルが前面のテクスチャ上にレンダリングされたり、その逆が起こったりする。
フリップ (flip)
バック バッファとフロント バッファのアドレスをスワップ (交換) すること。これにより、バック バッファ内のイメージをフロント バッファへコピーまたはブリットする必要がない。その結果、バック バッファ内にあったイメージを効率よく画面に表示できる。
フリッピング チェーン (flipping chain)
相互に接続されており、フリップ可能な一連のサーフェス。「フリップ」を参照すること。
フリッピング サーフェス (flipping surface)
フリッピング可能なメモリ。「フリップ」を参照すること。
フォーカス ウィンドウ (focus window)
Microsoft® DirectDraw® がウィンドウ メッセージを受け取るために使用するアプリケーション ウィンドウ。 実際に画面に表示される場合も、表示されない場合もある。フォーカス ウィンドウのメッセージ ハンドラは、DirectDraw により転送された入力メッセージを受け取る。アプリケーションが持つことのできるフォーカス ウィンドウは 1 つだけである。「デバイス ウィンドウ」を参照すること。
フレーム (frame)
シーン上のオブジェクトの配置の基になる非表示のボックス。シーン上でのオブジェクトの位置は、適切な基準フレームに対する空間的な関係を指定することによって決めることができる。ビジュアル オブジェクトは、その位置や向きをフレームから取得する。

動画やアニメーション内の単一のイメージも同様である。

フロント バッファ (front buffer)
グラフィックス アダプタによって変換され、モニタまたはほかの出力デバイスに表示されるメモリの矩形。
前方クリップ面 (front clipping plane)
視錐台の前面の限界。前方クリップ面よりもカメラ寄りにあるオブジェクトはレンダリングされない。前方クリップ面の高さにより、視野が決まる。「後方クリップ面」を参照すること。


G

ゲンロッキング (genlocking)
2 つのビデオ信号の同期を取る処理。ゲンロッキングされた信号は元の信号と同期が取れているため、元の信号とミキシングすることができ、ディゾルブ、ワイプなどのトランジション エフェクトが可能となる。
グリッド (grid)
拍 (ビート) の小分割。ビートごとのグリッド数は、Microsoft® DirectMusic® の拍子記号の一部である。
グルーブ レベル (groove level)
スタイルの再生中にミュージックに指定される値。グルーブ レベルによって、指定された時間に選択できるパターンが決定される。オーサーは、広範囲のグルーブ レベルを各パターンに割り当てる。
グループ (group)
プレーヤーの論理的な集まり。Microsoft® DirectPlay® は、セッション内でグループをサポートする。プレーヤーのグループを作成することにより、アプリケーションはグループに単一のメッセージを送信でき、グループ内のすべてのプレーヤーがそのメッセージを受信できる。グループは、ネットワークのマルチキャスト機能をアプリケーションに公開する手段になる。

グループは、セッション内のプレーヤーをまとめるために使用できる。プレーヤーは、1 つ以上のグループに属すことができる。DirectPlay では、グループやそのメンバシップを管理することができる。


H

HAL
Hardware Abstraction Layer (ハードウェア アブストラクション レイヤ) の略。HAL は、ハードウェアおよびデバイス ドライバのメカニズムにより構成され、個々のデバイス固有の実装の詳細をアプリケーションから隠す働きを担う。使用しているハードウェアが、アプリケーションから要求された機能を実装していなかった場合は、その機能をソフトウェアによりエミュレートする。
ハードウェア ブリット (ブロック転送) (hardware blitter)
ディスプレイ アダプタに組み込まれており、効果的なブリット処理を行うハードウェア コンポーネント。
HEL
Hardware Emulation Layer (ハードウェア エミュレーション レイヤ) の略。HEL は、ハードウェアがサポートしていない機能をソフトウェアによりエミュレートする。
HID
Human Interface Device (ヒューマン インターフェイス デバイス) の略。人間がコンピュータを制御できるデバイスを示す USB クラス。
ヒット検出 (hit detection)
「衝突検出」を参照すること。
ホスト (host)
Microsoft® DirectPlay® で、DPID_SYSMSG という ID を持つ仮想プレーヤー。ホストは、システム メッセージやセッション内のすべてのプレーヤーに送られるメッセージを管理する。
HREF
Horizontal REFresh (水平リフレッシュ) の略。HREF 信号は、ビデオ ストリーム内で、ディスプレイが新しい走査線を開始しようとしていることを知らせるときにアクティブになる。「VREF」を参照すること。
HRTF
Head-Related Transfer Function (頭部伝達関数) の略。異なる方向からくる音のピッチやタイミングに対してリスナーの生理機能が及ぼす影響の数学的表現。


I, J, K

インデックス パレット (index palette)
ほかのパレット オブジェクトのインデックスとなるエントリを持つ DirectDrawPalette オブジェクト。
IPX サービス プロバイダ (IPX service provider)
Internetwork Packet Exchange (IPX) プロトコルを使用してローカル エリア ネットワーク (LAN) 上で通信を行うために Windows Sockets を使用するサービス プロバイダ。このサービス プロバイダは、非保証のメッセージ交換だけをサポートする。1 台のコンピュータは、IPX を使用して 1 つの Microsoft® DirectPlay® セッションのみのホストとして機能する。
IRE 率 (IRE scale)
International Radio Engineers の割合。IRE は、ある要素を全要素にコピーするビデオ信号の輝度を定義する 0 ～ 100 までの範囲の値。IRE 値が高くなると、ビデオ信号の輝度が増加する。7.5 IRE の輝度ユニット (National Television System Committee (NTSC) 信号の黒によるカットオフのしきい値) では、NTSC ディスプレイ デバイスの電子銃はカットオフされ、画面にはイメージが表示されない。


L

遅延時間 (latency)
応答遅延時間。たとえば Microsoft® DirectSound® では、サウンド バッファが再生されてから実際にサウンドがスピーカから出てくるまでの間の時間である。Microsoft DirectPlay® では、パケットが指定された宛先に到達するまでの時間である。
ライト マップ (light map)
3D シーンのライティング情報の入ったテクスチャ。
ロビーアウェア アプリケーション (lobby-aware application)
ロビーからの起動を最小限サポートするアプリケーション。
ロビー クライアント (lobby client)
ユーザーのコンピュータ上で実行されるロビー管理ルーチン。 アプリケーションの起動、ユーザー インターフェイスの更新、ロビー サーバーとの通信を行う。
ロビー プロバイダ (lobby provider)
ロビー サーバーの開発者が提供するクライアント コンポーネント (ダイナミックリンク ライブラリ)。これには、Microsoft® DirectPlay® の要求に応じてロビー サーバーとの通信機能が実装される。
ロビー サーバー (lobby server)
リモート サーバー上で実行されるロビー管理ルーチン。ロビー サーバーは、管理対象のアプリケーションに接続してきたユーザーに関するすべての情報を調整する。
ロビー セッション (lobby session)
クライアントとサーバーが相互運用するよう特別に記述されていなかったロビー サーバーへの接続。


M

マッハ バンド (Mach bands)
3D プリミティブのブレンディングがスムーズに行われない色範囲。
マテリアル (material)
サーフェスがどのように光を反射および発色するかを決定する属性。マテリアル (素材) には、エミッション属性 (ライトに依存せず発色)、アンビエント属性、ディフューズ属性、およびスペキュラ属性の 4 つの構成要素がある。 反射の明るさは、強度の設定により決定される。
メッシュ (mesh)
単純なポリゴンで表現される面が集まったもの。
ミップマップ (mipmap)
MIP マップとも呼ばれる。MIP は、英語の "much in little" を意味するラテン語 �multium in parvo� の略。同一イメージが徐々に低解像度になっていく一連のテクスチャのことで、1 つのイメージに何種類ものフィルタをかけることにより作成される。オブジェクトが近くに表示されるときには高解像度のイメージが使用され、オブジェクトが遠ざかるに従って (つまり画面での表示が小さくなるに従って) 低解像度のイメージが使用される。
ミキシング (mixing)
Microsoft® DirectSound® で、再生中の複数のサウンド バッファを合成し、生成されたサウンドをプライマリ サウンド バッファ (サウンド ハードウェアにオーディオ データを出力するバッファ) へ書き込む処理。処理時間が範囲内に収まるかどうかを考慮しなければ、ミキシングできるバッファの数に制限はない。
モード X (Mode X)
標準 VGA のモード 13 から派生したハイブリッド ディスプレイ モード。 このモードでは、VGA ディスプレイ アダプタの EGA マルチ ビデオ平面システムを使用することにより、最大 256 KB のディスプレイ メモリが使用可能となっている (モード 13 で使用可能なディスプレイ メモリ量は 64 KB)。
モデル座標 (model coordinates)
ローカル原点に対する相対座標。「モデル空間」および「ワールド座標」を参照すること。
モデル空間 (model space)
単一の 3D モデル用のローカル原点に対する相対的な頂点を使用する (モデル座標のための) 基準フレーム。
マルチパス テクスチャ ブレンディング (multipass texture blending)
各パスごとに一度ずつテクスチャ上にブレンディングして、3D プリミティブを繰り返しレンダリングする手法。この手法は、さまざまな特殊効果を得るために幅広く使用されている。


N

ナグリング (nagling)
TCP/IP サービス プロバイダに、小さなデータ パケットをバッファに入れて大きなデータ パケットにしてから送信させるようにするアルゴリズム。ナグリングは、小さなデータ パケットを 1 つの大きなパケットに結合できるまで蓄積するか、事前のパケットの確認を受け取るまでサーバーに待機するよう要求することにより、TCP/IP サーバーが多くの非常に小さなパケットを送信しないようにする。ナグリングはメッセージ送信のオーバーヘッド (および必要な帯域幅) を削減できるが、小さなデータ パケットを送信する前に遅れが生じる (遅延時間が増える)。
法線ベクトル (normal vector)
サーフェスから垂直に伸びる架空のレイで、面の向きの定義に使用される。
NRPN
NonRegistered Parameter Number (非登録パラメータ番号) の略。非登録パラメータは異なるメーカーによる異なる機能に対して使用することができ、パラメータには MIDI コントローラを通してアクセスする。詳細については、MIDI の仕様を参照すること。


O

奇数フィールド (odd field)
ビデオ フレームを構成する奇数/偶数のフィールド セットの 1 つ目のフィールド。
オフスクリーン サーフェス (off-screen surface)
メモリ上の概念的な矩形領域。 一般に、表示する前にバック バッファへブリットするビットマップを格納するために使用する。通常、スプライトが格納される。
オペコード (opcode)
実行バッファ内の頂点を解釈する方法やシステムの状態を変更する方法を定義するオペレーション コード。
オーバードロー (overdraw)
スクリーン ピクセルが描画される平均回数。
オーバーレイ サーフェス (overlay surface)
メモリ上の概念的な矩形領域。 オーバーレイ サーフェスに格納されたイメージ情報は、そのオーバーレイ サーフェスが適用されるプライマリ サーフェスのイメージ情報の上に被せられる。オーバーレイは、その他のすべてのスクリーン要素よりも上にあるものとして処理される。
オーバーレイ Z オーダー (overlay z-order)
オーバーレイどうしのクリッピングの順番を決定する。 これにより、ハードウェア スプライト システムを Microsoft® DirectDraw® に実装することが可能になる。


P

ページ フリッピング (page flipping)
「フリップ」を参照すること。
パレット (palette)
オブジェクトやアプリケーションが使用する色セット。Microsoft® DirectX® では、DirectDrawPalette オブジェクトのことを指す。
パレット インデックス (palette index)
色を選択するときに使用されるパレット テーブル配列のインデックスとなる整数。
パレット化されたサーフェス (palettized surface)
アタッチされたパレットを色情報の格納場所として使用する DirectDrawSurface オブジェクト。
パン値 (pan value)
左右のオーディオ チャネルの相対音量。 100 分の 1 デシベル単位で表される。
パラレル ポイント (parallel point)
平行な光線でオブジェクトを照らすが、光の向きはその位置から決定されるような光源の記述。たとえば、パラレル ポイント光源の両側に置かれた 2 つのメッシュがある場合、各メッシュは光源に面している方の面が照らされる。
P チャンネル (PChannel)
Performance channel (パフォーマンス チャンネル) の略。特定のポート上にある特定のチャンネル グループ内の MIDI チャンネル。
PCM
Pulse Code Modulation (パルス符号変調) の略。非圧縮形式のウェーブ データ形式で、各値はサンプリング時の信号の振幅を表している。
ピアツーピア セッション (peer-to-peer session)
セッションの完全な状態がそのセッション内のすべてのコンピュータ上に複製される Microsoft® DirectPlay® セッション。セッション記述データ (プレーヤーとグループのリスト、および各セッションに関する名前とリモート データ) は、すべてのコンピュータに複製される。1 台のコンピュータで何か変更した場合は、ほかのすべてのコンピュータに即座に通知される。これは、DirectPlay の通信のデフォルト モードである。「クライアント/サーバー セッション」を参照すること。
パースペクティブ補正 (perspective correction)
遠近補正のこと。 カメラから角度をなして離れていくポリゴンにテクスチャ マップを適用する際に、ポリゴンの奥行きがわかるようにテクスチャをポリゴン上に広げる技法。Microsoft® Direct3D® では、パースペクティブ補正は自動的に行われる。
ピッキング (pick)
ビューポートの 2D 座標で与えられた場所にあるビジュアル オブジェクトをシーン内で探すこと。
PID
Physical Interface Device (物理インターフェイス デバイス) の略。人間がコンピュータからフォース フィードバックを感じることのできる USB クラス。
ピッチ (pitch)
ビットマップ ラインの先頭を表すアドレスと次のラインの先頭を表すアドレスの間の距離。 バイト単位で表される。すべてのディスプレイ メモリが 1 つの線形ブロックとして配置されているとは限らないので、メモリ ピッチとメモリ幅を混同しないこと。たとえば、矩形メモリのように、ビットマップの幅とキャッシュ部分が足されたものがディスプレイ メモリのピッチとなっている場合もある。「幅」および「ストライド」を参照すること。
プレーヤー (player)
Microsoft® DirectPlay® セッションの参加者。各プレーヤーには、プレーヤー間でのメッセージ交換を可能にするためにプレーヤー ID が与えられる。
プレーヤー ID (player ID)
Microsoft® DirectPlay® セッションの参加者の作成時に参加者に与えられる、その参加者固有の番号。アプリケーションは、プレーヤー ID を使用して参加者どうしにメッセージ交換を行わせる。ホストには、常に DPID_SYSMSG というプレーヤー ID が与えられる。
PNG
Portable Network Graphics (ポータブル ネットワーク グラフィックス) の略。劣化のない圧縮方式を使用するビットマップ フォーマット。特定のメーカーの所有物ではない。
ポイント ライト (point light)
その起点からすべての方向へ均等に光を照射する光源。
ポイント リスト (point list)
最も単純な 3D プリミティブ。3D 空間内の互いに接続されていない点の集まりである。
強度 (power)
マテリアルのスペキュラ属性で、スペキュラ ハイライトの鮮明度を決める値。この値が 5 のときは金属的な外観になり、値がもっと高くなるとよりプラスチック的な外観になる。
プライマリ サウンド バッファ (primary sound buffer)
最終的なオーディオ出力をミキシングして再生するオブジェクト。一般にはセカンダリ バッファのサウンドをミキシングした結果の出力先とされるが、カスタム ミキシングやその他の特別処理を行うために直接アクセスすることもできる。
プライマリ サーフェス (primary surface)
ディスプレイに表示されるイメージが格納されるメモリ領域。
射影空間 (projection space)
射影トランスフォームによってワールド空間の位置からトランスフォームされた頂点の入った基準フレーム。射影空間は、シーン上のすべての頂点が、－ 1.0 ～ 1.0 の範囲内の x 座標と y 座標、および 0.0 ～ 1.0 の範囲内の z 座標を持つ同次立方体空間である。遠近補正後同次空間と呼ばれる場合もある。
射影トランスフォーム (projection transformation)
頂点に行列を適用して、頂点をカメラ空間から射影空間へ変更するトランスフォーム。


Q

クオータニオン (quaternion)
ベクトルを定義する [x, y, z] 値に追加される 4 つ目の要素。3D 軸とその回りの回転を定義する。


R

参照カウント (reference count)
コンポーネント オブジェクト モデル (COM) オブジェクトをコントロールするためのカウンタ。参照カウントは、オブジェクトが作成されたときに 1 に設定される。 その後、インターフェイスがオブジェクトに結び付けられるたびにインクリメントされ、インターフェイス接続が切断されるとデクリメントされる。参照カウントが 0 になると、オブジェクトは破棄される。 破棄されたオブジェクトへのインターフェイスはすべて無効となる。
リージョン (region)
DLS では、楽器の音色を合成する際に、そのデジタル サンプルが使用される音色の範囲。
ルート フレーム (root frame)
Microsoft® Direct3D® での、親フレームを持たない (つまり、フレームの階層構造の最上位に位置する) フレーム。ルート フレームには、シーンを構成する一連のオブジェクトすべてが格納される。「シーン」を参照すること。
PRN
Registered Parameter Number (登録パラメータ番号) の略。登録パラメータ番号は MMA (MIDI Manufacturers Association) によって機能に割り当てられており、コントローラを通してアクセスできる。詳細については、MIDI の仕様を参照すること。


S

飽和 (saturation)
入力およびフォース フィードバックにおいて、軸が物理的な極限に達する前に最小値または最大値が取得または設定されるようにするために行う、軸の範囲に対する調整。範囲内の最大値が 1,000 で、最大飽和ポイントが 900 に設定されている場合、軸がその方向に 90% 移動すると、最大値に達する。
シーン (scene)
仮想環境を構成する一連のオブジェクトすべてを指す。 可視オブジェクト、サウンド、ライト、フレームが含まれる。Microsoft® Direct3D® では、ルート フレーム内のオブジェクト全体のことを指す。
スクリーン空間 (screen space)
座標がフレーム バッファ内の 2D (2 次元) の位置に直接マッピングされている基準フレーム。 ディスプレイやその他の表示デバイスに表示するためのフレームである。スクリーン空間の座標は、ビューポートのパラメータから作成したトランスフォーム行列を使用して射影空間の座標をトランスフォームすることにより得られる。
セカンダリ サウンド バッファ (secondary sound buffer)
1 つのサウンドまたはオーディオ ストリームを管理し、それをプライマリ サウンド バッファに対して再生するオブジェクト。
セキュア セッション (secure session)
セッションに参加する前に、既知のユーザーのデータベースに対してすべてのユーザーが認証されたセッション。セキュア セッションでは、Microsoft® DirectPlay® のシステム メッセージはすべてデジタル署名され、送信元の身元が確認される。機密性の高い情報を送信する特定のシステム メッセージは暗号化される。1 人のプレーヤーから発生し、セッション内のほかのすべてのプレーヤーにある要素を全要素にコピーしなければならないシステム メッセージは、まず最初にサーバーに送信される。その後、サーバーはメッセージに署名し、セッション内のほかのすべてのコンピュータにメッセージを転送する。デフォルトでは、プレーヤーからプレーヤーへのメッセージは署名されず、サーバー経由でルーティングされない。
センド (send)
(名詞) セカンド バッファにサウンド データを送信することで適用される、バッファに対するサウンド エフェクト。
サービス プロバイダ (service provider)
Microsoft® DirectPlay® がネットワークを介した通信を行うために使用するダイナミックリンク ライブラリ。サービス プロバイダには、メッセージを送受信するために必要となるネットワーク固有のコードがすべて含まれている。各種オンライン サービスやネットワーク オペレータは、サービス プロバイダを提供することにより、ハードウェア、プロトコル、通信媒体、ネットワーク資源などに特殊なものを使用することができる。
セッション (session)
Microsoft® DirectPlay® で、リモート コンピュータ上で実行され互いに通信しているいくつかのアプリケーションのインスタンス。アプリケーションがほかのコンピュータとの通信を開始する場合、アプリケーションはいずれかのセッションに属している必要がある。アプリケーションはネットワーク上の既存のセッションすべてを列挙し、それらの 1 つに参加したり、新しいセッションを作成し、作成したセッションにほかのコンピュータが参加するのを待機したりすることができる。アプリケーションがセッションの一部になると、プレーヤーを作成し、セッション内のほかのすべてのプレーヤーとメッセージを交換できる。
サウンド バッファ (sound buffer)
Microsoft® DirectSound® のオーディオ データを管理するオブジェクト。
転送元カラー キー (source color key)
ブリットの場合は転送でコピーされない色、オーバーレイの場合は出力先で表示されない色のこと。
スペキュラ属性 (specular property)
スペキュラ反射属性、ライトからの入射光の角度と視点への反射光の角度の両方に依存したマテリアル属性。マテリアルの光の反射および発色を決定する属性は 4 つあるが、スペキュラ属性はそのうちの 1 つである。「アンビエント属性」、「ディフューズ属性」、および「エミッション属性」を参照すること。
スポットライト (spotlight)
円錐状の光を放つ光源。円錐の中にあるオブジェクトだけが照らされる。円錐は 2 つの輝度を生成する。 中央の明るい部分はポイント ライトと同じ働きをし、周囲の薄暗い部分は周辺の暗い影とマージされる。
スタティック バッファ (static buffer)
サウンド全体を保持するセカンダリ サウンド バッファ。通常、データは 1 回だけ書き込まれる。「ストリーミング バッファ」と比較すること。
スティッキー フォーカス (sticky focus)
Microsoft® DirectSound® で、バッファを所有するアプリケーションが入力フォーカスを持っていないときにもサウンド バッファを再生できる能力。たとえば、ユーザーがほかのアプリケーションで作業している間にも、DirectSound アプリケーションはサウンド バッファを再生し続けることができる。
ストリーミング バッファ (streaming buffer)
サウンドの一部だけを保持するセカンダリ サウンド バッファ。ストリーミング バッファのデータは、再生に合わせてリフレッシュされなければならない。「スタティック バッファ」と比較すること。
伸縮 (stretching)
サイズの異なる転送先にイメージをブリットすること。この処理を直接サポートするハードウェアもある。
ストライド (stride)
ピッチ の同義語。「幅」を参照すること。
サーフェス (surface)
ビジュアル イメージが格納されるメモリ。たいていの場合はディスプレイ メモリ内に置かれるが、システム メモリに置くこともできる。「複合サーフェス」、「オフスクリーン サーフェス」、「オーバーレイ サーフェス」および「プライマリ サーフェス」を参照すること。
維持期間 (sustain)
フォース フィードバック エフェクトの基本マグニチュードが到達されている期間。 アタックからフェードまでの間。
システム メッセージ (system message)
Microsoft® DirectPlay® では、プレーヤー ID の DPID_SYSMSG からのメッセージ。すべてのシステム メッセージは DWORD 値で始まる。


T

TCP/IP サービス プロバイダ (TCP/IP service provider)
TCP/IP プロトコルを使用してインターネットやローカル エリア ネットワーク (LAN) 上で通信を行うために Windows Sockets を使用するサービス プロバイダ。非保証メッセージに User Datagram Protocol (UDP) パケットを使用し、保証付きメッセージに TCP を使用する。TCP/IP を使用して、1 台のコンピュータは、複数の Microsoft® DirectPlay® セッションとして機能できる。
テアリング (tearing)
スクリーンのリフレッシュ レートがアプリケーションのフレーム レートと同期していないときに発生する、表示がうねるように見える現象。1 つのフレームの上部が別のフレームの下部と同時に表示され、2 つのイメージの間に裂け目が生じる。
テッセレーション (tessellation)
3D グラフィックスでオブジェクトのサーフェスを三角形ポリゴンに細分化すること。
テクセル (texel)
テクスチャ内の単一の要素。テクスチャがオブジェクトに適用されたとき、テクセルがスクリーン上のピクセルに対応することはめったにない。アプリケーションは、テクスチャ フィルタリングを使用して、シーン内にピクセルを作成するためにシステムがテクセル間を補間する方法を制御できる。
テクスチャ (texture)
Microsoft® Direct3D® でビジュアル オブジェクトに適用される、ピクセルが矩形に並んだ配列。
テクスチャ ブレンディング (texture blending)
テクスチャの色をマップ先のサーフェスの色と組み合わせる技法。
テクスチャ座標 (texture coordinates)
各テクスチャのどのテクセルがオブジェクトの各頂点に割り当てられるかを決める座標。
テクスチャ フィルタリング (texture filtering)
1 つまたは複数のテクスチャから得たテクセルの色を、3D プリミティブのイメージを構成するピクセルにマップする処理。
テクスチャ マッピング (texture mapping)
テクスチャをオブジェクトに適用すること。テクスチャはフラットなイメージなのに対し、多くの場合オブジェクトは立方体であるため、テクスチャは、テクスチャ座標とラッピング フラグを使用して、オブジェクトの表面にマップされなければならない。「テクスチャ座標」および「ラップ」を参照すること。
スラッシング (thrashing)
次のフレームでテクスチャ メモリを再利用するよう、現在のフレームで使用したテクスチャを削除すること。
スロットリング (throttling)
元の伝送形態よりもメッセージを早く送信しないよう、メッセージ数を制限すること。


U

単位ベクトル (unit vector)
マグニチュード (長さ) 1.0 のベクトル。
USB
Universal Serial Bus (ユニバーサル シリアル バス) の略。


V

VBI
Vertical Blanking Interval (垂直帰線消去間隔) の略。ある要素を全要素にコピーするビデオでは、ビデオ フレーム間に短い時間がある。 この間に、ディスプレイ デバイスは次のフレームのためにディスプレイをリフレッシュする。
ベロシティ (velocity)
ミュージックでは、MIDI キーが押される速度。この速度は、いくつかの音色のティンバーでノートが再生される動的レベルとほぼ等しい。

3D サウンドでは、ドップラー シフトを計算するために使用される、音源またはリスナーが移動していると見なされる場合の速度。

頂点 (vertex)
3D 空間のポイント。
ビデオ フレーム (video frame)
ビデオ ストリーム内の単一のイメージ。 1 つの奇数フィールドと 1 つの偶数フィールドから成る。「フィールド」を参照すること。
ビュー空間 (view space)
「カメラ空間」を参照すること。
ビュー トランスフォーム (view transformation)
モデルの頂点に行列を適用して、モデルの向きをワールド空間からビュー空間へ変えるトランスフォーム。
視錐台 (viewing frustum)
ビューポートのカメラに対して相対的に配置されたシーン内の 3D ボリューム。視錐台の中にあるオブジェクトは、画面に表示される。遠近ビューでは、前方クリップ面と後方クリップ面の間にある仮想的なピラミッド型のボリュームとなる。正射ビューでは、立方体になる。
ビューポート (viewport)
3D シーンがどのように 2D ウィンドウにレンダリングされるかを決める矩形。ビューポートは、デバイス上での、オブジェクトがレンダリングされる領域も決める。
VREF
Vertical REFresh (垂直リフレッシュ) の略。VREF は、ビデオ ストリーム内で、ディスプレイが新しい画面を開始しようとしていることを知らせるときにアクティブになる。「HREF」を参照すること。


W

幅 (width)
メモリ内に格納されているビットマップの 1 つのラインの始点を表すアドレスとそのラインの終点を表すアドレスの距離。この距離は、メモリ内でのビットマップの幅だけを表すものである。矩形メモリ内のキャッシュなど、ビットマップの次のラインの始点に達するまでに必要となるような余分なメモリは、この距離には含まれない。
ワールド座標 (world coordinates)
シーンの頂点に達する相対座標。「モデル座標」および「ワールド空間」を参照すること。
ワールド空間 (world space)
ワールド座標 (3D シーン内の単一の原点に対する相対的な頂点を表す) により使用される基準フレーム。
ワールド トランスフォーム (world transformation)
モデルの頂点に行列を適用して、モデルの向きをモデル空間からワールド空間へ変えるトランスフォーム。
ラップ (wrap)
面やメッシュのテクスチャ座標の計算に使用されるプロシージャ。基本的なラッピング タイプには、フラット、円柱、球状、クロムがある。


X, Y, Z

Z バッファ (z-buffer)
シーン上の各ピクセルの深度を格納したバッファ。z 値の小さいピクセルは z 値の大きいピクセルを上書きする。
Z ファイティング (z fighting)
「フリマリング」を参照すること。


トピックが見つかりません

クリックしたリンク先のトピックが見つかりません。考えられる原因と対処方法は以下のとおりです。

  • リンク先のトピックを含むファイル (.chm) が適切な位置にない。

    対処方法 : MSDN ライブラリ セットアップを再度、実行する。

  • 現在のトピック、またはリンク先のトピックを含むファイル (.chm) が古いため、リンク情報が適切に設定されていない。

    対処方法 : 最新の MSDN ライブラリをインストールする。

  • MSDN ライブラリ CD が CD-ROM ドライブにない。

    対処方法 : MSDN ライブラリ CD を CD-ROM ドライブに挿入する。

Built on 2000年11月20日


Microsoft DirectX 8.0

動作環境

API 要素の構文を紹介する各トピックには、これらの要素を使うときに必要となる、ビルドおよび実行時の動作環境についての情報が含まれている。動作環境の書式は、次のとおりである。

Windows NT/2000 : Windows 2000 以降に対する再配布可能ファイルとして提供。
Windows 95/98 : Windows 95 以降に対する再配布可能ファイルとして提供。
Windows CE : バージョン 1.0 以降が必要。
ヘッダー : winuser.h で宣言。
インポート ライブラリ : user32.lib を使用。
Unicode : Windows NT/2000 上の Unicode および ANSI バージョンとして実装される。

1 行目では、API 要素をサポートしている Windows NT のバージョンについての情報が記述されている。この情報には、必要とされるサービス パック、オプション パック、または Internet Explorer などのコンポーネントについての情報が含まれる。Windows NT または Windows 2000 で API 要素がサポートされていない場合は、"Windows NT/2000 : 未対応。" という書式で表される。

2 行目では、API 要素が Windows 95 または Windows 98 上でサポートされているかどうかについての情報が記述されている。この情報には、必要とされる OEM サービス リリース、再配布可能かどうか、または Internet Explorer などのコンポーネントについての情報が含まれる。Windows 95 または Windows 98 で API 要素がサポートされていない場合は、"Windows 95/98 : 未対応。" という書式で表される。

3 行目では、API 要素をサポートしている Windows CE のバージョンについての情報が記述されている。Windows CE で API 要素がサポートされていない場合は、"Windows CE : 未対応。" という書式で表される。

4 行目では、API 要素が定義されているファイルについての情報が記述されている。この情報には、.h ファイル、.idl ファイル、または .odl ファイルについての情報が含まれる。ヘッダー ファイルがユーザーによって提供される場合は、"ヘッダー : ユーザー定義。" という書式で表される。

5 行目では、関数またはメンバへの呼び出しの解決に使用されるファイルについての情報が記述されている。この情報には、.lib ファイル、.dll ファイル、または .tlb ファイルについての情報が含まれる。インポート ライブラリがユーザーによって提供される場合は、"インポート ライブラリ : ユーザー定義。" という書式で表される。インポート ライブラリを必要としない API 要素では、この行は省略される。

6 行目では、API 要素が Unicode (W) バージョンおよび ANSI (A) バージョンの両方でサポートされているかどうかについての情報が記述されている。API 要素が Unicode バージョンでサポートされていない場合、この行は省略される。

Built on 2000年11月20日